nuevoMailer v.10.0   User's guide
 

nuevoMailer API

General

For nuevoMailer SB/MB/WP and ESP v.4.
Below you will find PHP code ready to copy-paste and use.
In these samples make sure you replace $myapiKey and $baseURL with your own api key and nuevoMailer installation url.
Check also the file examples.php in the /api/ folder in your package. It includes all available methods so you can test in a very convenient way.
Response format
In most of the following examples the Accept header determines the response type. 
    "Accept: application/json" //Returns the data as a json string
    "Accept: text/html"         //Returns data in a table
What's common in all methods
First define your nuevoMailer installation URL and your api key. 
    $myapiKey = "your_own_api_key";     //From your administrators table
    $baseURL  = "https://mydomain.com/mailer";    //Your nuevoMailer installation URL
In each method you change the endpoint accordingly. You will see all available endpoints below.
PHP code for GET 

    $endpoint = "/api/v7/admin/";    //Change here
    $url = $baseURL.$endpoint;
    $request = curl_init($url);
    curl_setopt($request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
    curl_setopt($request, CURLOPT_FRESH_CONNECT, true);
    curl_setopt($request, CURLOPT_HEADER, 0);
    curl_setopt($request, CURLOPT_POST, 0);
    curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($request, CURLOPT_TIMEOUT, 30);
    curl_setopt($request, CURLOPT_FOLLOWLOCATION, 0);
    curl_setopt($request, CURLOPT_SSL_VERIFYPEER, 0);
    curl_setopt($request, CURLOPT_HTTPHEADER, array(
     "X-Apikey: ".$myapiKey,
     "Accept: application/json",     //Or text/html to rerurn data in a table.
     "Content-type: application/json"
    ));
    $response = curl_exec($request);
    //if($errno = curl_errno($request)) {$error_message = curl_strerror($errno);echo "CURL error ({$errno}):\n {$error_message}"; }
    echo $response;
PHP code for POST
With a POST we are sending data so we must also define $DataToUse. You will see examples below specific to each case. 

    $endpoint = "/api/v7/subscribers";    //Change here
    $url = $baseURL.$endpoint;
    $request = curl_init($url);
    curl_setopt($request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
    curl_setopt($request, CURLOPT_FRESH_CONNECT, true);
    curl_setopt($request, CURLOPT_HEADER, 0);
    curl_setopt($request, CURLOPT_POST, 1);
    curl_setopt($request, CURLOPT_POSTFIELDS, $DataToUse);  //Change here
    curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($request, CURLOPT_TIMEOUT, 5);
    curl_setopt($request, CURLOPT_FOLLOWLOCATION, 0);
    curl_setopt($request, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($request, CURLOPT_HTTPHEADER, array(
     "X-Apikey: ".$myapiKey,
     "Accept: application/json",
     "Content-Type: application/json",
     "Content-Length: " . strlen($DataToUse) //Change here
    ));
    $response = curl_exec($request);
    //if($errno = curl_errno($request)) {$error_message = curl_strerror($errno);echo "CURL error ({$errno}):\n {$error_message}"; }
    echo $response;
PHP code for DELETE 

    $endpoint = "/api/v7/subscribers/email@domain.com";    //Change here
    $url = $baseURL.$endpoint;
    $request = curl_init($url);
    curl_setopt($request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
    curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($request, CURLOPT_CUSTOMREQUEST, "DELETE");
    curl_setopt($request, CURLOPT_HTTPHEADER, array("X-Apikey: ".$myapiKey));
    $response = curl_exec($request);
    //if($errno = curl_errno($request)) {$error_message = curl_strerror($errno);echo "CURL error ({$errno}):\n {$error_message}"; }
    echo $response;
PHP code for PUT
With a PUT we are also sending details about what to update so we must also define $DataToUse. You will see examples below specific to each case. 

    $endpoint = "/api/v7/subscribers";    //Change here
    $url = $baseURL.$endpoint;
    $request = curl_init($url);
    curl_setopt($request, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
    curl_setopt($request, CURLOPT_HEADER, 0);
    curl_setopt($request, CURLOPT_POST, 1);
    curl_setopt($request, CURLOPT_POSTFIELDS, $DataToUse);  //Change here
    curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($request, CURLOPT_CUSTOMREQUEST, "PUT");
    curl_setopt($request, CURLOPT_HTTPHEADER, array(
     "X-Apikey: ".$myapiKey,
     "Content-Type: application/json",
     "Accept: application/json",
     "Content-Length: " . strlen($DataToUse)    //Change here
    ));
    $response = curl_exec($request);
    //if($errno = curl_errno($request)) {$error_message = curl_strerror($errno);echo "CURL error ({$errno}):\n {$error_message}"; }
    echo $response;

Administrator

HTTP method Endpoint Function Notes Api versions
GET /api/v7/admin Get admin account details Returns the administrator details owner of the api key used 3-7
Sample response: 
[
    {
        "idAdmin":"1",
        "email":"admin@admin.com",
        "name":"Master admin",
        "role":"Administrator"
    }
]

Subscribers

HTTP method Endpoint Function Notes Api versions
GET /api/v7/subscribers Get all subscribers Html (tabular) or Json depending on the accept headers sent. 2-7
The response is an array of all subscribers that includes all fixed and custom subscriber fields: 

    [
        {
            "idEmail":"1",
            "email":"xxxxx@hotmail.com",
            "field1":"....",
            "another_field":"...."
        },
        {
            "idEmail":"2",
            "email":"zzzzz@gmail.com",
            "field1":"....",
            "another_field":"...."
        },

    ]
GET /api/v7/subscribers/email@domain.com Get one subscriber by email Same as above but for a specific subscriber 2 - 7
GET /api/v7/subscribers/email@domain.com/lists Get one subscriber's lists 2 - 7
Sample response includes list IDs, names, opt-in dates and verified status. 
[
    [
        {"idList":"2","listName":"My other list","iDate":"2021-03-06 13:52:45","verified":"-1"},
        {"idList":"1","listName":"My first list","iDate":"2021-03-06 13:53:38","verified":"0"}
    ]
GET /api/v7/subscribers/email@domain.com?list=ID Is the subscriber in this list? false: not in list.
0: yes but unverified
-1: yes and verified. 		2 - 7
Sample response: 

    [
        {"Result":"true","Verified":"-1"}
    ]
GET /api/v7/subscribers?list=ID All subscribers (emails) under a list. It is like a GET for all subscribers but in this case it is limited to a specific list. 2 - 7
GET /api/v7/fields Custom subscriber fields Returns a json string with the idCustomField as id, reference name (key) and display name (label) of all active custom subscriber fields. 3 - 7
Sample response: 

    [
        {"id":"1","key":"customSubField1","label":"Name"},
        {"id":"2","key":"customSubField2","label":"Last name"},
        {"id":"3","key":"customSubField3","label":"Title"}
    ]
DELETE /api/v7/subscribers/email@domain.com Delete a subscriber If the subscriber does not exist the "Result" is "not-found" 2 - 7
Sample response: 
{"action":"deletion", "email": "email@domain.com", "result":"success"}
POST /api/v7/subscribers/ Add a new subscriber. But in addition you can,
Remove globally or from list(s).
Create a transactional email.
Update existing.
With or w/o double opt-in.
With or w/o sending greeting emails.
The post is rerouted to optIn.php (or optOut.php).
For a complete list of arguments and features see below.		 2 - 7
Parameter Opt-in Opt-out Required?
General options
api action add remove Always
idSenderProfile The id of the sender profile to use if also sending an email. Yes if you want to send also an email. The default sender profile is used if omitted. Leave empty for ESP v.4.
api_send_email To disable Welcome/Goodbye emails set it to “no”. Defaults to “yes” if omitted and emails will be sent.
double_optin 0: disables double opt-in.
-1: enables it.		 Non applicable. No. If omitted it is inherited from the related Sender profile setting.
opt_out_type Non applicable. 1: Lists opt-out
2: Global opt-out		 No. If omitted it defaults to Global opt-out.
check_optouts If given as true, it will check for list and global opt-outs and will not add the subscriber. So it works as filter based on previous opt-outs. Non applicable. Optional.
Not in ESP v.4
lists Give the list IDs, separated by commas.
"lists" => "50,53,55, X, Y,Z";
Another variation is:
"idList" => array(1,2); 		No. But it may be handy to use especially in opt-ins.
Subscriber related
email Always required. Everything else is optional.
Custom fields To add more subscriber data, go to your “Custom fields” page and see the reference name of a field.
For example: if you use customSubField1 for “First Name” you add this line:
"customSubField1" => "Jason",
Note: multiple choice values should be passed in this way.
Assuming customSubField10 is “My favorite colors”.
"customSubField10"=>"Blue||Green"
tags To add tags to a subscriber give the subscriber tag IDs separated by commas.
"5, 2, 4"		 Optional
remove_tags To remove tags from a subscriber give the subscriber tag IDs separated by commas.
"1, 3"		 Optional.
Not in ESP v.4
ipSubscribed Refers to opt-in IP. Optional.
SB/MB v.10.1+
ESP v.4.1+
WP v.10+
Transactional / trigger emails
trigger_newsletter Enter the newsletter ID as you see it in your newsletters table.
Comment/remove the line if you don’t want to trigger a newsletter.
trigger_only Can take “yes” or “no”. With yes, you are using the api just for the transactional email. With no, the rest of the process continues whether it is an opt-in or opt-out.
trigger_delay Enter value in seconds. When to send the email after the action completed. Use 0 and in this case it will be sent with the next cron run.
Sample data for adding a subscriber with a POST 

    $subData = array(
        "idSenderProfile" => 1, //replace with the id
        "api_action" => "add",
        "api_send_email" => "no", //since you are not sending an email the sender profile will not be used.
        "email" => "email@domain.com",
        "double_optin" => 0,
        "lists" => "1,2",         //Lists IDs, separated with commas
        "tags"  => "2,3",         //Tag IDs, separated with commas
        "customSubField1" => "John",
        "customSubField2" => "Doe"
    );
    $DataToUse=json_encode($subData);
Sample data for removing a subscriber with a POST 

    $subData = array(
        "api_action" => "remove",      //For merely removing a subscriber you can also do a DELETE.
        "api_send_email" => "no",
        "email" => "email@domain.com",
        "opt_out_type" => 2,        //2: global opt-out, 1: lists opt-out.
        "lists" => "1,2"         //Lists IDs, separated with commas, if opt_out_type above is 1
    );
    $DataToUse=json_encode($subData);
Sample data for a transactional (trigger) email with a POST
Send only a newsletter without any further action and with or without adding this email to your subscribers.
This will create an email trigger. The cron job #4 should be running in order to send the triggered emails. 

    $subData = array(
        "idSenderProfile" => 1,         //replace with the id
        "email" => "email@domain.com",
        "trigger_newsletter"=>"ID",    //The newsletter ID that you want to send
        "trigger_only"=>"yes",         //yes, no. If yes,the opt-in process will stop
        "trigger_delay"=>20,           //Required. Value in seconds. It is added to the current time. Use 0 to send it as soon as possible.
        "api_action" => "add"
    );
    $DataToUse=json_encode($subData);

Variation for creating a transactional (trigger) email with a POST
Since SB/MB v.9.7. Not in ESP v.4.
This creates only a trigger email using settings from an existing trigger (sender profile, newsletter-to-send etc)
POST url is /subscribers/
You cannot create a new subscriber with this.
The cron job #4 should be running in order to send the triggered emails. 

        $subData = array(
            "api_action" => "add",           // Required. Always use: add
            "trigger_only"=>"yes",           // Required. Always use: yes
            "email" => "email@domain.com",
            "idTrigger"=>"1",                // Required trigger id
            "trigger_delay"=>20           //Required. Value in seconds. It is added to the current time. Use 0 to send it as soon as possible.
        );
        $DataToUse=json_encode($subData);
    Further notes
  1. You can combine the opt-in/-out process with a trigger newsletter.
  2. Or you can use the api only for opt-in or opt-out or just for triggering a newsletter.
  3. Do not use the trigger just for welcome/goodbye emails since you can do this in other ways.
  4. The api_action parameter is required when you use the api just for a trigger (without opt-in/-out). Use “add” in this case
PUT /api/v7/subscribers/ Suppress subscriber 2 - 7
Sample response: 

    {"action":"suppression", "email": "email@domain.com", "result":"success"}

Mailing lists

HTTP method Endpoint Function Notes Api versions
GET /api/v7/lists Get all lists including subscribers in total Html (tabular) or Json depending on the accept headers sent.
Response is an array of all lists fields/values including total subscribers, verified_subscribers, unverified_subscribers.		 2 - 7
GET /api/v7/lists/ID Get one list by its ID including subscribers in total Same as above but for a specific list. 2 - 7
GET /api/v7/lists/list_name Get one list by its name including subscribers in total Same as above. 2 - 7
DELETE /api/v7/lists/ID Delete a list Response is {"result":"success"} 2 - 7
POST /api/v7/lists/ Create a new list Will return data about the newly created list. 2 - 7
Sample data for creating a new list with POST or updating an existing list with a PUT: 

    $listData = array(
        "listName" => "My new list",
        "listDescription" => "Created using the API",
        /*Only needed when updating an existing list with PUT*/
        "idList"=>2,
        /*With a PUT you can use any other field here from the lists table. For example,*/
        "isPublic"=>-1,                 //To set the list as public
        "fromName"=>"By me",            //Deprecated since v.9.5
        "fromEmail"=>"me@mydomain.com", //Deprecated since v.9.5
        "listSMTP"=>serialize(array("3"))   ////Deprecated since v.9.5. Assign smtp server with ID 3 to this list.
    );
    $DataToUse=json_encode($listData);
So if you want to create a new list with custom settings, do a POST, grab the id of the new list and update it with a PUT.
PUT /api/v7/lists/ Update a list Will return data about the updated list in Html (tabular) or Json depending on the accept headers sent. 2 - 7

Newsletters

HTTP method Endpoint Function Notes Api versions
GET /api/v7/newsletters A list of titles of public newsletters Html with a link to the newsletter page or Json depending on the accept headers sent. 2 - 7
GET /api/v7/newsletters/?format=html Format can be html or text. Only public newsletters are loaded.
Accept: text/html => Returns a list of clickable newsletter titles.
Accept: application/json => A json array of all newsletters data.		 5 - 7
GET /api/v7/newsletters/menu Creates a drop-down menu of titles: on selection it loads the newsletter underneath in an iframe. Html 2 - 7.
Not in ESP v.4
GET /api/v7/newsletters/ID Display a newsletter in an iframe Accept: text/html => Complete Html display (v1-v5) Accept: application/json => json array of this newsletter data (v5)
2 - 7
GET /api/v7/newsletters/ID/links
Or
/api/v7/newsletters/ID/links?start=2023-05-04&end=2023-05-29 		Returns all clicked links for a specific newsletter with their "apiEndPoint" to retrieve subscribers (see below) start/end dates are optional and can be used independently. If given use YYYY-MM-DD. 2 - 7
Since v.9.9 and ESP v.4
GET /api/v7/newsletters/ID/links/subscribers
Or
/api/v7/newsletters/ID/links/subscribers?start=2023-05-04&end=2023-05-29 		Same as above but will also include subscribers. start/end dates are optional and can be used independently. If given use YYYY-MM-DD. 2 - 7
Since v.9.9 and ESP v.4
GET /api/v7/newsletters/ID/links?link=base64Encoded(linkURL)
Or
/api/v7/newsletters/ID/links?link=base64Encoded(linkURL)?start=2023-05-04&end=2023-05-29 		Returns all subscribers who clicked a specific link with date, IP and other data for this particular newsletter.
Sample apiEndPoint:
"http://domain.com/mailer/api/v7/newsletters/ID/links?link=aHR0cHM6Ly93d3cubnVldm9tYWlsZXIuY29tL2RvY3MvaGVscF8zLnBocCNwcmVoZWFkZXJz"		 start/end dates are optional and can be used independently. If given use YYYY-MM-DD.
The linkURL should be base64 encoded. You can take it from the apiEndPoint (2 steps above)		 2 - 7
Since v.9.9 and ESP v.4
POST /api/v7/newsletters/ Create/add a newsletter Will return the ID of the newly created newsletter. The body as string should be properly escaped. You will find an example in the file newsletter.php in your api folders. 2 - 7
Sample data for creating a newsletter with POST or updating it with a PUT: 

    $newsletterData = array(
        "name" => "Created using the API",
        "body" => "...a string....",
        "html" => -1,    //-1 for html, 0 for a text newsletter. Defaults to -1 if omitted
        "isPublic" => -1, //-1 for Yes, 0 for No. Defaults to 0 if omitted
        /* The ID is only required when updating an existing newsletter with PUT.
          With a PUT you can only update the name and body. */
        "ID"=>2
    );
    $DataToUse=json_encode($newsletterData);
PUT /api/v7/newsletters/ Update an existing newsletter See code above. Requires ID, body, name as strings, properly escaped. Check the file newsletter.php in your api folders. 2 - 7
DELETE /api/v7/newsletters/ID Delete a newsletter by its ID Returns {"result":"success"} 2 - 7

Campaigns

HTTP method Endpoint Function Notes Api versions
GET /api/v7/campaigns Returns all fields from all campaigns 2 - 7
GET /api/v7/campaigns/ID Returns all fields from a specific campaign 2 - 7
GET /api/v7/campaigns/ID/stats Get campaign key statistics like in summary report 2 - 7
GET /api/v7/campaigns/ID/links
Or
/api/v7/campaigns/ID/links?start=2023-05-04&end=2023-05-29 		Returns all clicked links in a campaign with their "apiEndPoint" to retrieve subscribers (see below) start/end dates are optional and can be used independently. If given use YYYY-MM-DD. 2 - 7
Since v.9.9 and ESP v.4
GET /api/v7/campaigns/ID/links/subscribers
Or
/api/v7/campaigns/ID/links/subscribers?start=2023-05-04&end=2023-05-29 		Same as above but will also include subscribers. start/end dates are optional and can be used independently. If given use YYYY-MM-DD. 2 - 7
Since v.9.9 and ESP v.4
GET /api/v7/campaigns/ID/links?link=base64Encoded(linkURL)
Or
/api/v7/campaigns/ID/links?link=base64Encoded(linkURL)?start=2023-05-04&end=2023-05-29 		Returns all subscribers who clicked a specific link with date, IP and other data.
Sample apiEndPoint:
"http://domain.com/mailer/api/v7/campaigns/ID/links?link=aHR0cHM6Ly93d3cubnVldm9tYWlsZXIuY29tL2RvY3MvaGVscF8zLnBocCNwcmVoZWFkZXJz"		 start/end dates are optional and can be used independently. If given use YYYY-MM-DD.
The linkURL should be base64 encoded. You can take it from the apiEndPoint (2 steps above)		 2 - 7
Since v.9.9 and ESP v.4
POST /api/v7/campaigns/ Creates a new campaign Returns the newly created campaign details (like a GET). 2 - 7
PUT /api/v7/campaigns/ Updates a campaign. You can use all the campaign data presented below. The ID is requited. Updates all details (content, lists etc), pauses or resumes a campaign Returns the newly created campaign details (like a GET). 2 - 7
POST & PUT parameters for creating/updating a campaign
Parameter Comments
idSenderProfile The ID of the sender profile to use. If empty it will use the default sender profile. Not applicable to ESP v.4.
campaignName Optional
fromName Optional
fromEmail Optional
replyToEmail Optional
idHtmlNewsletter Html newsletter ID or 0 if you are sending a Text one.
idTextNewsletter Text newsletter ID or 0 if you are sending an Html one. If you define both the Html and the Text IDs it will be multipart.
lists Comma-separated values with list IDs.
Use "all" for all lists.
Use "" for all subscribers.
xLists Excluded lists: comma-separated values with list IDs.
tagsFilter Comma-separated values with subscriber tag IDs
tagsFilterOPR Options: AND, OR. Refers to the tags above.
tagsFilterExcluded Comma-separated values with tag IDs. You exclude subscribers having these tags.
idSendFilter Comma-separated values of mailing filter IDs. Optional.
doNotTrackCampaign Use 0 or -1 to activate. Optional.
anonymousTracking Use 0 or -1 to activate. Optional.
excludeAdminImported Use 0 or -1 to activate. Optional.
Not applicable to ESP v.4.
activation Activation date-time in this format: YYYY-MM-DD HH:MM:SS. Leave empty to start now.
sendHours Comma-separated values of hours like: 00,06,13,23. If omitted defaults to -1 which means all hours.
sendDays Comma-separated values of days. Sunday is 0. If omitted defaults to -1 which means all days.
batch_size You may use 0 in case you want to send all in one go (not recommended). If omitted it is taken from the related Sender profile.
Not applicable to ESP v.4 - globally defined settings are used.
batch_pause Batch pause in minutes. You may use 0 and let the cron do the timing. If omitted it is taken from the related Sender profile.
Not applicable to ESP v.4 - globally defined settings are used.
dailyMax Maximum amount of emails per day for this campaign only. Use 0 for unlimited.
prefers 3 for All, 1 for Html, 2 for Text. Defaults to 3 if omitted.
confirmed 3 for All, 1 for Yes, 2 for No. Defaults to 3 if omitted.
For multi-threaded campaigns
isQueued -1 will create a multi-threaded campaign. Leave empty or omit it for regular campaigns.
Not applicable to ESP v.4 since all campaigns are by default queued.
numberOfThreads A number. Applies only to multi-threaded campaigns.
Not applicable to ESP v.4 - globally defined settings are used.
threadsDistance In seconds. Applies only to multi-threaded campaigns.
Not applicable to ESP v.4 - globally defined settings are used.
Sending by URL
url Send a web page by its URL. Omit if sending a newsletter.
subject Only when sending by URL. Omit otherwise.
attachments Only when sending a URL. Comma separated complete file names that exist in the attachments folder.
optoutLink Only when sending a URL. Appends an opt-out-link. 0: no, -1: yes
Google analytics parameters
utm_source Optional.
utm_medium Optional.
utm_campaign Optional.
utm_term Optional.
utm_content Optional.
Pausing, updating a campaign
pause -1 with a POST creates the campaign and sets it as paused.
Omit or use 0 when creating the campaign.
When using PUT you can switch between -1/0 to pause/resume a campaign.
ID The ID is only required when updating an existing campaign with PUT.
Sample data for creating a new campaign with POST or updating an existing campaign with PUT: 

    $campaignData = array(
        "idSenderProfile" => 1,
        "campaignName" => "Test campaign with the api",
        "idHtmlNewsletter" => 8,
        "idTextNewsletter" => 20,
        "lists"=>"1,3",
        "batch_size"=>100,
        "batch_pause"=>2,
        "dailyMax"=>5000,
        "prefers"=>3,
        "confirmed"=>1,
        /* pause -1 creates (or sets the campaign when using PUT) as paused.
                    Omit or use 0 when creating the campaign.
                    When using PUT you can switch between -1/0 to pause/resume a campaign. */
        "pause"=>"0",
        /* The ID is only required when updating an existing campaign with PUT.*/
        "ID" =>36
    );
    $DataToUse=json_encode($campaignData);
DELETE /api/v7/campaigns/ID Delete a campaign by its ID Returns {"result":"success"} 2 - 7

Opt-outs

HTTP method Endpoint Function Notes Api versions
GET /api/v7/optouts?start=2023-01-01&end=2023-02-19 Give start-end dates in YYYY-MM-DD format.
Return in json or as a table depending on the "Accept" header. 		7 (in v.9.7)

Subscriber tags

HTTP method Endpoint Function Notes Api versions
GET /api/v7/subscribertags Response includes tag id and name.
Return in json or as a table depending on the "Accept" header. 		4 - 7

Sender profiles

HTTP method Endpoint Function Notes Api versions
GET /api/v7/senderprofiles Response includes profile id and name.
Return in json or as a table depending on the "Accept" header. 		7
Not applicable to ESP v.4

API keys

You will find your api keys in your administrators page. Go to: Menu>Tools>Administrator accounts>View & edit Make sure that the Api key belongs to an active administrator account.
 
 
© 2024 Designerfreesolutions