nuevoMailer API

General

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
Argument 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 also send an email. The default sender profile is used if omitted.
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 your system-wide settings are used.
opt_out_type Non applicable. 1: Lists opt-out
2: Global opt-out
No. If omitted your system-wide settings are used.
lists Give the list IDs, separated by commas.
"50,53,55, X, Y,Z"
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 Give the subscriber tags IDs, separated by commas.
"5, 2, 4"
Optional
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 serder 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 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,           //value in seconds, use 0 to send it as soon as possible.*/
        "api_action" => "add"
    );
    $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",
        "fromEmail"=>"me@mydomain.com",
        "listSMTP"=>serialize(array("3"))   //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
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
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
POST /api/v7/campaigns/ Create a new campaign Will return the newly created campaign details (like a GET). 2 - 7
Sample data for creating a new campaign with POST or updating an existing campaign with PUT:

    $campaignData = array(
        /*The id of the sender profile to use*/
        "idSenderProfile" => 1,
        "campaignName" => "Test campaign with the api",
        "fromName" =>"from-name.tld",
        "fromEmail" =>"from-email@my-domain.tld",
        "replyToEmail" =>"reply-to-email@my-domain.tld",
        /*Give the Html newsletter ID or 0 if you are sending a Text one.*/
        "idHtmlNewsletter" => 8,
        /*Give the Text newsletter ID or 0 if you are sending an Html one.*/
        "idTextNewsletter" => 20,
        /*The list IDs with commas. Use "all" for all lists. Use "" for  all subscribers.*/
        "lists"=>"1,3",
        /*Send a webpage by its URL. Leave blank if sending a newsletter.*/
        "url" => "",
        /*Only when sending by URL. Leave blank otherwise.*/
        "subject" => "",
        /*Only when sending a URL. Comma separated complete file names that exist in the attachments folder.*/
        "attachments"=>"",
        /*Only when sending a URL. Appends an opt-out-link. 0: no, -1: yes*/
        "optoutLink" => "-1",
        /*Activation date-time in this format: YYYY-MM-DD HH:MM:SS. Leave empty to start now.*/
        "activation" => "",
        /*Batch size.  You may use 0 in case you want to send all in one go (not recommended)*/
        "batch_size"=>100,
        /*Batch pause in minutes. You may use 0 and let the cron do the timing.*/
        "batch_pause"=>2,
        /*Maximum amount of emails per day. Use 0 for unlimited*/
        "dailyMax"=>5000,
        /*3:all, 1:html, 2:text*/
        "prefers"=>3,
        /*3:all, 1:yes, 2:no*/
        "confirmed"=>1,
        /*Google parameters. Optional. Only the first 3 are required.*/
        "utm_source" =>"",
        "utm_medium" => "",
        "utm_campaign" => "",
        "utm_term" => "",
        "utm_content" => "",
        /* 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);
                
PUT /api/v7/campaigns/ You can use all the campaign data presented above. The ID is requited. Updates all details (content, lists etc), pauses or resumes a campaign Will return the newly created campaign details (like a GET). 2 - 7
DELETE /api/v7/campaigns/ID Delete a campaign by its ID Returns {"result":"success"} 2 - 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

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.
 
 
© 2022 Designerfreesolutions