evoMailer Subscriber 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 evoMailer installation url.
You will find your api key in your administrator page. Go to: Menu>Configuration>Administrator
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 evoMailer installation URL and your api key. 
    $myapiKey = "your_own_api_key";     //From your administrators table
    $baseURL  = "https://mydomain.com/mailer";    //Your evoMailer installation URL
In each method you change the endpoint accordingly. You will see all available endpoints below.
PHP code for GET 

    $endpoint = "/api/v1/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, 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/v1/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/v1/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/v1/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;

Subscribers

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

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

    [
        {"id":"1","key":"customSubField1","label":"Name"},
        {"id":"2","key":"customSubField2","label":"Last name"},
        {"id":"3","key":"customSubField3","label":"Title"}
    ]
DELETE /api/v1/subscribers/email@domain.com Delete a subscriber If the subscriber does not exist the "Result" is "not-found" v1
Sample response: 
{"action":"deletion", "email": "email@domain.com", "result":"success"}
POST /api/v1/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.		 v1
Argument Opt-in Opt-out Required?
General options
idSenderProfile Sender profile ID. If not given it will use the default.
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.		 No. If omitted it will use the Sender profile settings.
If double opt-in is active for this profile then the subscriber is added to the list(s) as unconfirmed and the confirmation email will be sent (unless it is overridden with api_send_email=>no).
opt_out_type Non applicable. 1: Lists opt-out
2: Global opt-out		 No. If omitted defaults to a 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
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 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
ipSubscribed Refers to the opt-in IP. Since v.1.5. 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_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 #5 should be running in order to send the triggered emails. 

    $subData = array(
        "email" => "email@domain.com",
        "api_action" => "add",          //"add" will also create a subscriber. Use "remove" if you only want to create an email trigger.
        "trigger_newsletter"=>ID,    //The newsletter ID that you want to send
        "idSenderProfile"=>ID,       // Sender profile ID. If not given it will use the default.
        "trigger_delay"=>20,           //value in seconds, use 0 to send it as soon as possible.*/
        "api_send_email" => "no"      //No need to send an email since we are creating an email trigger. No effect for  "api_action" => "remove"
    );
    $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/v1/subscribers/ Suppress subscriber v1
Sample response: 

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