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/apiv4/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/apiv4/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/apiv4/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/apiv4/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 /apiv3/admin Get admin account details Returns the administrator details owner of the api key used apiv3, apiv4, apiv5
Sample response:
[
    {
        "idAdmin":"1",
        "email":"admin@admin.com",
        "name":"Master admin",
        "role":"Administrator"
    }
]

Subscribers

HTTP method Endpoint Function Notes Api versions
GET /api/v5/subscribers Get all subscribers Html (tabular) or Json depending on the accept headers sent. apiv2, apiv3, apiv4, apiv5
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/v5/subscribers/email@domain.com Get one subscriber by email Same as above but for a specific subscriber apiv2, apiv3, apiv4, apiv5
GET /api/v5/subscribers/email@domain.com/lists Get one subscriber's lists apiv2, apiv3, apiv4, apiv5
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/v5/subscribers/email@domain.com?list=ID Is the subscriber in this list? false: not in list.
0: yes but unverified
-1: yes and verified.
apiv2, apiv3, apiv4, apiv5
Sample response:

    [
        {"Result":"true","Verified":"-1"}
    ]
GET /api/v5/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. apiv2, apiv3, apiv4, apiv5
GET /apiv3/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. apiv3, apiv4, apiv5
Sample response:

    [
        {"id":"1","key":"customSubField1","label":"Name"},
        {"id":"2","key":"customSubField2","label":"Last name"},
        {"id":"3","key":"customSubField3","label":"Title"}
    ]
    
DELETE /api/v5/subscribers/email@domain.com Delete a subscriber If the subscriber does not exist the "Result" is "not-found" apiv2, apiv3, apiv4, apiv5
Sample response:
{"action":"deletion", "email": "email@domain.com", "result":"success"} 
POST /api/v5/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.
apiv2, apiv3, apiv4, apiv5
Argument Opt-in Opt-out Required?
General options
api action add remove Always
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_list_id A list ID. If a value is given then the email  is sent with the custom list settings (if defined for this list).
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(
        "api_action" => "add",
        "api_send_email" => "no",
        "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(
        "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_list_id"=>"ID",       //A list ID. If given then it will use the  custom list settings of this list.
        "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/v5/subscribers/ Suppress subscriber apiv2, apiv3, apiv4, apiv5
Sample response:

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

Mailing lists

HTTP method Endpoint Function Notes Api versions
GET /api/v5/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.
apiv2, apiv3, apiv4, apiv5
GET /api/v5/lists/ID Get one list by its ID including subscribers in total Same as above but for a specific list. apiv2, apiv3, apiv4, apiv5
GET /api/v5/lists/list_name Get one list by its name including subscribers in total Same as above. apiv2, apiv3, apiv4, apiv5
DELETE /api/v5/lists/ID Delete a list Response is {"result":"success"} apiv2, apiv3, apiv4, apiv5
POST /api/v5/lists/ Create a new list Will return data about the newly created list. apiv2, apiv3, apiv4, apiv5
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
        "listUseCustomSettings"=>-1,    //To enable custom list settings
        "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/v5/lists/ Update a list Will return data about the updated list in Html (tabular) or Json depending on the accept headers sent. apiv2, apiv3, apiv4, apiv5

Newsletters

HTTP method Endpoint Function Notes Api versions
GET /api/v5/newsletters A list of titles of public newsletters Html with a link to the newsletter page or Json depending on the accept headers sent. apiv2, apiv3, apiv4, apiv5
GET /api/v5/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.
apiv5
GET /api/v5/newsletters/menu Creates a drop-down menu of titles: on selection it loads the newsletter underneath in an iframe. Html apiv2, apiv3, apiv4, apiv5
GET /api/v5/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)
apiv2, apiv3, apiv4, apiv5
POST /api/v5/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. apiv2, apiv3, apiv4, apiv5
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/v5/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. apiv2, apiv3, apiv4, apiv5
DELETE /api/v5/newsletters/ID Delete a newsletter by its ID Returns {"result":"success"} apiv2, apiv3, apiv4, apiv5

Campaigns

HTTP method Endpoint Function Notes Api versions
GET /api/v5/campaigns Returns all fields from all campaigns apiv2, apiv3, apiv4, apiv5
GET /api/v5/campaigns/ID Returns all fields from a specific campaign apiv2, apiv3, apiv4, apiv5
GET /api/v5/campaigns/ID/stats Get campaign key statistics like in summary report apiv2, apiv3, apiv4, apiv5
POST /api/v5/campaigns/ Create a new campaign Will return the newly created campaign details (like a GET). apiv2, apiv3, apiv4, apiv5
Sample data for creating a new campaign with POST or updating an existing campaign with PUT:

    $campaignData = array(
        "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/v5/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). apiv2, apiv3, apiv4, apiv5
DELETE /api/v5/campaigns/ID Delete a campaign by its ID Returns {"result":"success"} apiv2, apiv3, apiv4, apiv5

Subscriber tags

HTTP method Endpoint Function Notes Api versions
GET /api/v5/subscribertags Response includes tag id and name.
Return in json or as a table depending on the "Accept" header.
apiv2, apiv3, apiv4, apiv5

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
Visit nuevoMailer.com
Visit the Demo