API Documentation | LABNIFY

API Documentation

NAV

Introduction

The Labnify API documentation builds on the virtually extended instance of Mailwizz/MTA. Combined a Mailer and relay engine into one webapp, you can send emails directly via your panel or API.

This is the documentation for Labnify API.

In order to integrate Labnify with 3rd-party apps or any custom apps, you can use its powerful API.

The API is providing the basic operations needed for your implementation.

This document will drive you through the Labnify available SDKs .

Available implementations:

The PHP SDK

Compatible implementations:

The Python SDK.

The Ruby SDK.

A small rest app that acts as a proxy between Labnify and any other software.

Node.js implementations.

HTTP Methods used

We follow the REST standards for Labnify's API interaction, which means that we use following HTTP methods during communication:

  • POST - when items are created

  • GET - when items are listed

  • PUT - when items are updated

  • DELETE - when items are deleted

You will have to make sure your server supports all these methods.

If you are doing API calls and get HTTP Forbidden errors, when updating or deleting items, it means your server does not support PUT/DELETE and you must change it's configuration to allow these methods.

Authorization

Authentication is done by sending your API key in a custom header called X-Api-Key.

API-URL

https://api.labnify.com/api/index.php

Data Format

When sending data to the API endpoints, it is sent in form-data format and returned as json.

Getting started

First you need to install the SDK. See each supported language for its way of installing

PHP

Get started by installing it via composer as follows:

composer require ems-api/php-client

Then follow the instructions from examples/setup.php file.

Python

You can either download the latest version of the code, or you can install it via pip as follows:

pip install mailwizz-python-sdk

Then follow the instructions from examples/setup_api.py file.

Ruby

You can download or clone the latest version of the code.

git clone https://github.com/twisted1919/mailwizz-ruby-sdk.git

You will need to have Ruby installed:

https://www.ruby-lang.org/en/documentation/installation/

The following gem is required: excon

sudo gem install excon

Then, follow the instructions from examples/setup_api.rb file.

Setup

Please make sure to replace API-URL PUBLIC-KEY, with their proper values:

//Require the autoloader class if you haven't used composer to install the package require_once __DIR__ . '/../vendor/autoload.php'; //Configuration object (Get your API info from: https://kb.mailwizz.com/articles/find-api-info/) : $config = new \EmsApi\Config([ 'apiUrl' => 'API-URL', 'apiKey' => 'PUBLIC-KEY', // components 'components' => [ 'cache' => [ 'class' => \EmsApi\Cache\File::class, 'filesPath' => __DIR__ . '/data/cache', // make sure it is writable by webserver ] ], ]); //Now inject the configuration and we are ready to make api calls \EmsApi\Base::setConfig($config); //Start UTC date_default_timezone_set('UTC');

See each language tab for the setup instructions.

Notes

Lists

Lists endpoint

/ CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\Lists();

Get all lists

// GET ALL ITEMS $response = $endpoint->getLists($pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "12", "total_pages": 2, "current_page": 1, "next_page": 2, "prev_page": null, "records": [ { "general": { "list_uid": "tz601yx7aa61b", "name": "Testing list #4", "display_name": "Testing list", "description": "Testing list" }, "defaults": { "from_name": "Test user", "reply_to": "[email protected]", "subject": "" }, "notifications": { "subscribe": "no", "unsubscribe": "no", "subscribe_to": "", "unsubscribe_to": "" }, "company": { "name": "Support", "address_1": "Test", "address_2": "", "zone_name": "Constanta", "city": "Constanta", "zip_code": "1234x", "phone": "", "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]", "country": { "country_id": "1", "name": "Afghanistan", "code": "AF" } } }, { "general": { "list_uid": "zh103m6twfcd2", "name": "Testing list #5", "display_name": "Testing list", "description": "Testing list" }, "defaults": { "from_name": "Test user", "reply_to": "[email protected]", "subject": "" }, "notifications": { "subscribe": "no", "unsubscribe": "no", "subscribe_to": "", "unsubscribe_to": "" }, "company": { "name": "Support", "address_1": "Test", "address_2": "", "zone_name": "Constanta", "city": "Constanta", "zip_code": "1234x", "phone": "", "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]", "country": { "country_id": "1", "name": "Afghanistan", "code": "AF" } } } ] } }

This endpoint retrieves all the lists.

HTTP Request

GET API-URL/lists

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one list

// get a single list $response = $endpoint->getList('LIST-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "general": { "list_uid": "cn417nrhmv922", "name": "Testing list #4", "display_name": "Testing list", "description": "Testing list" }, "defaults": { "from_email": "[email protected]", "from_name": "User Test", "reply_to": "[email protected]", "subject": "" }, "notifications": { "subscribe": "no", "unsubscribe": "no", "subscribe_to": "", "unsubscribe_to": "" }, "company": { "name": "Support", "address_1": "Test", "address_2": "", "zone_name": "Constanta", "city": "Constanta", "zip_code": "1234x", "phone": "", "address_format": "[COMPANY_NAME]\n[COMPANY_ADDRESS_1] [COMPANY_ADDRESS_2]\n[COMPANY_CITY] [COMPANY_ZONE] [COMPANY_ZIP]\n[COMPANY_COUNTRY]\n[COMPANY_WEBSITE]", "country": { "country_id": "1", "name": "Afghanistan", "code": "AF" } } } } }

This endpoint retrieves the list with the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id which to retrieve.

Create a list

// create a new list // please see countries.php example file for a list of allowed countries/zones for list company $response = $endpoint->create([ // required 'general' => [ 'name' => 'My list created from the API', // required 'description' => 'This is a test list, created from the API.', // required ], // required 'defaults' => [ 'from_name' => 'John Doe', // required 'from_email'=> '[email protected]', // required 'reply_to' => '[email protected]', // required 'subject' => 'Hello!', ], // optional 'notifications' => [ // notification when new subscriber added 'subscribe' => 'yes', // yes|no // notification when subscriber unsubscribes 'unsubscribe' => 'yes', // yes|no // where to send the notifications. 'subscribe_to' => '[email protected]', 'unsubscribe_to' => '[email protected]', ], // optional, if not set customer company data will be used 'company' => [ 'name' => 'John Doe INC', // required 'country' => 'United States', // required 'zone' => 'New York', // required 'address_1' => 'Some street address', // required 'address_2' => '', 'zone_name' => '', // when country doesn't have required zone. 'city' => 'New York City', 'zip_code' => '10019', ], ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "list_uid": "hv4163y076d84" }

This endpoint creates a list.

The $data param can contain following indexed arrays:

-> general - required

-> defaults - required

-> notifications - optional

-> company - optional, if not set customer company data will be used

Please see countries.php example file for a list of allowed countries/zones for list company

HTTP Request

POST API-URL/lists

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list details. The following indexed arrays are accepted: general, defaults, notifications, company

General block - required

ParameterTypeRequiredDescription
namestringyesList name
descriptionstringyesList description

Defaults block - required

ParameterTypeRequiredDescription
from_namestringyesFrom name
from_emailstringyesFrom email
reply_tostringyesReply to email
subjectstringnoList subject

Notifications block - optional

ParameterTypeRequiredDescription
subscribeYes/NonoNotification when new subscriber added
unsubscribeYes/NonoNotification when new subscriber unsubscribe
subscribe_tostringnoWhere to send the notifications on subscribe
unsubscribe_tostringnoWhere to send the notifications on unsubscribe

Company block - optional - if not set customer company data will be used

ParameterTypeRequiredDescription
namestringyesCompany name
countrystringyesCompany country
zonestringyesCompany zone
address_1stringyesCompany address
address_2stringnoCompany address 2
zone_namestringnoCompany address - when country doesn't have required zone.
citystringnoCompany city
zipcodestringnoCompany zipcode

Update a list

// update list // please see countries.php example file for a list of allowed countries/zones for list company $response = $endpoint->update('LIST-UNIQUE-ID', [ // required 'general' => [ 'name' => 'My list created from the API - now updated!', // required 'description' => 'This is a test list, created from the API.', // required ], // required 'defaults' => [ 'from_name' => 'John Doe', // required 'from_email'=> '[email protected]', // required 'reply_to' => '[email protected]', // required 'subject' => 'Hello!', ], // optional 'notifications' => [ // notification when new subscriber added 'subscribe' => 'yes', // yes|no // notification when subscriber unsubscribes 'unsubscribe' => 'yes', // yes|no // where to send the notifications. 'subscribe_to' => '[email protected]', 'unsubscribe_to' => '[email protected]', ], // optional, if not set customer company data will be used 'company' => [ 'name' => 'John Doe INC', // required 'country' => 'United States', // required 'zone' => 'New York', // required 'address_1' => 'Some street address', // required 'address_2' => '', 'zone_name' => '', 'city' => 'New York City', 'zip_code' => '10019', ], ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint updates a list.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID

URL Segment

SegmentTypeRequiredDescription
LIST-UNIQUE-IDstringyesList unique identifier

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list details. The following indexed arrays are accepted: general, defaults, notifications, company. See the create section for details

Copy a list

// copy a list $response = $endpoint->copy('LIST-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "list_uid": "hv4163y076d84" }

This endpoint copy the list with the given LIST-UNIQUE-ID.

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/copy

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to copy.

Delete a list

// delete a list $response = $endpoint->delete('LIST-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint will delete the list with the given LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to delete.

Fields

List fields endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\ListFields();

Get all list fields

// GET ALL ITEMS $response = $endpoint->getFields('LIST-UNIQUE-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "records": [ { "field_id": "12", "tag": "EMAIL", "label": "Email", "required": "yes", "help_text": null, "visibility": "visible", "sort_order": "0", "type": { "name": "Text", "identifier": "text", "description": "Text" } }, { "field_id": "13", "tag": "FNAME", "label": "First name", "required": "no", "help_text": null, "visibility": "visible", "sort_order": "1", "type": { "name": "Text", "identifier": "text", "description": "Text" } }, { "field_id": "14", "tag": "LNAME", "label": "Last name", "required": "no", "help_text": null, "visibility": "visible", "sort_order": "2", "type": { "name": "Text", "identifier": "text", "description": "Text" } } ] } }

This endpoint retrieves all the fields of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/fields

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one list field

// GET ONE ITEM $response = $endpoint->getField('LIST-UNIQUE-ID', 'FIELD-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "field_id": "13", "tag": "FNAME", "label": "First name", "required": "no", "help_text": null, "visibility": "visible", "sort_order": "1", "type": { "name": "Text", "identifier": "text", "description": "Text" } } } }

This endpoint retrieves the list field with the given FIELD-ID for the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to retrieve field for.
FIELD-IDyesList field id to retrieve

Create a list field

// create a new list field $response = $endpoint->create('LIST-UNIQUE-ID', [ 'type' => 'dropdown', 'label' => 'Text Label', 'tag' => 'DROPDOWN', 'required' => 'no', 'visibility' => 'visible', 'sort_order' => 0, 'help_text' => 'Help', 'default_value' => '', 'description' => 'Description', 'options' => [ [ 'name' => 'Option1', 'value' => 'Value1' ], [ 'name' => 'Option2', 'value' => 'Value2' ], ] ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "field_id": "138", "label": "Text Label", "tag": "DROPDOWN", "help_text": "Help", "description": "Description", "default_value": "", "required": "no", "visibility": "visible", "sort_order": "0", "type": { "name": "Dropdown", "identifier": "dropdown", "description": "Dropdown" }, "list": { "list_uid": "wo16508sn983b", "display_name": "My list" }, "options": { "Value1": "Option1", "Value2": "Option2" } } } }

This endpoint creates a list field.

The data param can contain following indexed arrays:

-> options - optional

HTTP Request

POST API-URL/lists/LIST_UID/fields

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list field details. The following indexed arrays are accepted: options

General block - required

ParameterTypeRequiredDescription
typestringyesThe field type check the field types endpoint for possible values
labelstringyesThe label of the field
tagstringyesThe unique tag
requiredstringyesWhether the field is required or not (yes/no)
visibilitystringyesWhether the field is visible or not (hidden/visible)
default_valuestringnoThe field default value
sort_orderintnoThe field showing order in the form
help_textstringnoThe field help text
descriptionstringnoThe field description
min_lengthintnoApplies for the text fields. Min length
max_lengthintnoApplies for the text fields. Max length maximum allowed value is 255
content_rulestringnoApplies for the text fields. Allows rules as alpha_ci/alphanum_ci/alphanumext_ci
content_regexstringnoApplies for the text fields. Regex to validate the field value
allowed_schemestringnoApplies for the url field
whitelist_domainsstringnoApplies for the url field
blacklist_domainsstringnoApplies for the url field
max_starsintnoApplies for the rating field
default_countrystringnoApplies for the phone field. Country codes values like us/ro/bg

Options block - optional

ParameterTypeRequiredDescription
namestringyesThe option name to show in the dropdown
valuestringyesThe option value for the dropdown

Update a list field

// update list field $response = $endpoint->update('LIST-UNIQUE-ID', 'FIELD-ID', [ 'label' => 'Text Label', 'tag' => 'DROPDOWN', 'required' => 'no', 'visibility' => 'visible', 'sort_order' => 0, 'help_text' => 'Help', 'default_value' => '', 'description' => 'Description', 'options' => [ [ 'name' => 'Option1', 'value' => 'Value1' ], [ 'name' => 'Option2', 'value' => 'Value2' ], ] ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "field_id": "138", "label": "Text Label", "tag": "DROPDOWN", "help_text": "Help", "description": "Description", "default_value": "", "required": "no", "visibility": "visible", "sort_order": "0", "type": { "name": "Dropdown", "identifier": "dropdown", "description": "Dropdown" }, "list": { "list_uid": "wo16508sn983b", "display_name": "My list" }, "options": { "Value1": "Option1", "Value2": "Option2" } } } }

This endpoint updates a list field.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/fields/FIELD-ID

URL Segment

SegmentTypeRequiredDescription
LIST-UNIQUE-IDstringyesList unique identifier
FIELD-IDstringyesList field id

PUT Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list field details. The following indexed arrays are accepted: options See the create section for details

General block - required

ParameterTypeRequiredDescription
labelstringyesThe label of the field
tagstringyesThe unique tag
requiredstringyesWhether the field is required or not (yes/no)
visibilitystringyesWhether the field is visible or not (hidden/visible)
default_valuestringnoThe field default value
sort_orderintnoThe field showing order in the form
help_textstringnoThe field help text
descriptionstringnoThe field description min_length
max_lengthintnoApplies for the text fields. Max length
content_rulestringnoApplies for the text fields. Allows rules as alpha_ci/alphanum_ci/alphanumext_ci
content_regexstringnoApplies for the text fields. Regex to validate the field value
allowed_schemestringnoApplies for the url field
whitelist_domainsstringnoApplies for the url field
blacklist_domainsstringnoApplies for the url field
max_starsintnoApplies for the rating field
default_countrystringnoApplies for the country field. Country codes values like us/ro/bg

Options block - optional

ParameterTypeRequiredDescription
namestringyesThe option name to show in the dropdown
valuestringyesThe option value for the dropdown

Delete a list field

// Delete FIELD $response = $endpoint->delete('LIST-UNIQUE-ID', 'FIELD-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint will delete the list field with the given FIELD-ID for the LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID/fields/LIST-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to delete.
FIELD-IDyesList field id to delete

Get all list field types

// GET ALL ITEMS $response = $endpoint->getListFieldTypes(); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "20", "records": [ { "name": "Text", "identifier": "text", "description": "Text" }, { "name": "Dropdown", "identifier": "dropdown", "description": "Dropdown" }, { "name": "Multiselect", "identifier": "multiselect", "description": "Multiselect" }, { "name": "Date", "identifier": "date", "description": "Date" }, { "name": "Datetime", "identifier": "datetime", "description": "Datetime" }, { "name": "Textarea", "identifier": "textarea", "description": "Textarea" }, { "name": "Country", "identifier": "country", "description": "Country" }, { "name": "State", "identifier": "state", "description": "State" }, { "name": "Checkbox List", "identifier": "checkboxlist", "description": "Checkbox List" }, { "name": "Radio List", "identifier": "radiolist", "description": "Radio List" }, { "name": "Geo Country", "identifier": "geocountry", "description": "Geo Country" }, { "name": "Geo State", "identifier": "geostate", "description": "Geo State" }, { "name": "Geo City", "identifier": "geocity", "description": "Geo City" }, { "name": "Checkbox", "identifier": "checkbox", "description": "Checkbox" }, { "name": "Consent Checkbox", "identifier": "consentcheckbox", "description": "Consent Checkbox" }, { "name": "Years Range", "identifier": "yearsrange", "description": "Years Range" }, { "name": "Phone Number", "identifier": "phonenumber", "description": "Phone Number" }, { "name": "Email", "identifier": "email", "description": "Email" }, { "name": "Url", "identifier": "url", "description": "Url" }, { "name": "Rating", "identifier": "rating", "description": "Rating" } ] } }

This endpoint retrieves all the list field types.

HTTP Request

GET API-URL/lists/fields/types

Segments

List segments endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\ListSegments();

Get all list segments

// GET ALL ITEMS $response = $endpoint->getSegments('LIST-UNIQUE-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "1", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "segment_uid": "yx536w32xt946", "name": "test", "subscribers_count": 289 } ] } }

This endpoint retrieves all the segments of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one list segment

// GET ONE ITEM $response = $endpoint->getSegment('SEGMENT-UNIQUE-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "segment_uid": "sx795qzttl9bb", "segment_id": "11", "name": "my segment with cond updated", "operator_match": "any", "date_added": "10/23/23, 2:36 PM", "subscribers_count": 0, "conditions": [ { "field_id": "96", "operator_id": "3", "value": "keyword" } ], "campaign_conditions": [] } } }

This endpoint retrieves the list segment with the given SEGMENT-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to retrieve segment for.
SEGMENT-UNIQUE-IDyesSegment unique id to retrieve

Get all subscribers

// GET ALL SUBSCRIBERS OF A LIST SEGMENT $response = $endpoint->getSubscribers('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "13", "total_pages": 2, "current_page": 1, "next_page": 2, "prev_page": null, "records": [ { "subscriber_uid": "ll381bxshm01e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" }, { "subscriber_uid": "tl269bw0ol42e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" }, { "subscriber_uid": "gs870cmwgve71", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:17" }, { "subscriber_uid": "nz753vyrm0f86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:17" }, { "subscriber_uid": "sf449a4k7n193", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "op6219zx1s149", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "zz449poqsr2af", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint retrieves all the subscribers of a list segment.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/segments/SEGMEMT-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers
SEGMENT-UNIQUE-IDyesSegment unique identifier

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Create a list segment

// create a new list segment $response = $endpoint->create('LIST-UNIQUE-ID', [ // required 'name' => 'My list segment created from the API', // required 'operator_match' => 'any', // required (any/all) // optional 'conditions' => [ [ 'field_id' => '96', // required . 'operator_id' => '3', // required . See the API-URL/lists/segments/condition-operators endpoint 'value' => 'domain.com', // required ], [ 'field_id' => '95', // required . 'operator_id' => '4', // required . See the API-URL/lists/segments/condition-operators endpoint 'value' => 'keyword', // required ] ], 'campaign_conditions' => [ [ 'action' => 'click', // required (click/open) 'campaign_id' => '100', // required 'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq) 'time_value' => '3', // required 'time_unit' => 'day' // required (day/month/year) ], [ 'action' => 'open', // required (click/open) 'campaign_id' => '99', // required 'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq) 'time_value' => '3', // required 'time_unit' => 'month' // required (day/month/year) ] ], ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "segment_uid": "xs655vtkcx569", "name": "my segment with cond" } } }

This endpoint creates a list segment.

The data param can contain following indexed arrays:

-> conditions - optional

-> campaign_conditions - optional

HTTP Request

POST API-URL/lists/LIST_UID/segments

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions,

General block - required

ParameterTypeRequiredDescription
namestringyesList segment name
operator_matchstringyesOperator to match all the conditions: any/all

Conditions block - optional

ParameterTypeRequiredDescription
field_idstringyesList custom field id. Can be retrieved using the list fields endpoint
operator_idstringyesOperator id. See the API-URL/lists/segments/operators endpoint
valuestringyesValue to compare with

Campaign conditions block - optional

ParameterTypeRequiredDescription
actionstringyesCampaign action: click/open
campaign_idintegeryesCampaign id.
time_comparison_operatorstringyesTime comparison operator: (lte/lt/gte/gt/eq)
time_valueintegeryesTime value
time_unitstringyesTime unit day/month/year

Update a list segment

// update list segment // Only the conditions present here will be kept. All other existing conditions will be removed $response = $endpoint->update('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID', [ // required 'name' => 'My list segment created from the API updated', // required 'operator_match' => 'any', // required (any/all) // optional 'conditions' => [ [ 'field_id' => '96', // required . 'operator_id' => '3', // required . See the API-URL/lists/segments/condition-operators endpoint 'value' => 'domain.com', // required ], [ 'field_id' => '95', // required . 'operator_id' => '4', // required . See the API-URL/lists/segments/condition-operators endpoint 'value' => 'keyword', // required ] ], 'campaign_conditions' => [ [ 'action' => 'click', // required (click/open) 'campaign_id' => '100', // required 'time_comparison_operator' => 'lte', // required (lte/lt/gte/gt/eq) 'time_value' => '3', // required 'time_unit' => 'day' // required (day/month/year) ], [ 'action' => 'open', // required (click/open) 'campaign_id' => '99', // required 'time_comparison_operator' => 'gte', // required (lte/lt/gte/gt/eq) 'time_value' => '3', // required 'time_unit' => 'month' // required (day/month/year) ] ], ]); // and get the response echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint updates a list segment.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segment

SegmentTypeRequiredDescription
LIST-UNIQUE-IDstringyesList unique identifier
SEGMENT-UNIQUE-IDstringyesList segment unique identifier

PUT Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the list segment details. The following indexed arrays are accepted: conditions, campaign_conditions. See the create section for details

General block - required

ParameterTypeRequiredDescription
namestringyesList segment name
operator_matchstringyesOperator to match all the conditions: any/all

Conditions block - optional

ParameterTypeRequiredDescription
field_idstringyesList custom field id. Can be retrieved using the list fields endpoint
operator_idstringyesOperator id. See the API-URL/lists/segments/operators endpoint
valuestringyesValue to compare with

Campaign conditions block - optional

ParameterTypeRequiredDescription
actionstringyesCampaign action: click/open
campaign_idintegeryesCampaign id.
time_comparison_operatorstringyesTime comparison operator: (lte/lt/gte/gt/eq)
time_valueintegeryesTime value
time_unitstringyesTime unit day/month/year

Delete a list segment

// Delete SEGMENT $response = $endpoint->delete('LIST-UNIQUE-ID', 'SEGMENT-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint will delete the list segment with the given SEGMENT-UNIQUE-ID for the LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID/segments/SEGMENT-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to delete.
SEGMENT-UNIQUE-IDyesList segment unique id to delete

Get all list segment condition operators

// GET ALL ITEMS $response = $endpoint->getConditionOperators(); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "10", "records": [ { "operator_id": "1", "name": "is", "slug": "is" }, { "operator_id": "2", "name": "is not", "slug": "is-not" }, { "operator_id": "3", "name": "contains", "slug": "contains" }, { "operator_id": "4", "name": "not contains", "slug": "not-contains" }, { "operator_id": "5", "name": "starts with", "slug": "starts" }, { "operator_id": "6", "name": "ends with", "slug": "ends" }, { "operator_id": "7", "name": "is greater than", "slug": "greater" }, { "operator_id": "8", "name": "is less than", "slug": "less" }, { "operator_id": "9", "name": "not starts with", "slug": "not-starts" }, { "operator_id": "10", "name": "not ends with", "slug": "not-ends" } ] } }

This endpoint retrieves all the list segment condition operators.

HTTP Request

GET API-URL/lists/segments/condition-operators

Subscribers

Subscribers endpoint

/ CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\ListSubscribers();

Get all subscribers

// GET ALL ITEMS $response = $endpoint->getSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "13", "total_pages": 2, "current_page": 1, "next_page": 2, "prev_page": null, "records": [ { "subscriber_uid": "ll381bxshm01e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" }, { "subscriber_uid": "tl269bw0ol42e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" }, { "subscriber_uid": "gs870cmwgve71", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:17" }, { "subscriber_uid": "nz753vyrm0f86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:17" }, { "subscriber_uid": "sf449a4k7n193", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "op6219zx1s149", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "zz449poqsr2af", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:16" }, { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint retrieves all the subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one subscriber

// GET ONE ITEM $response = $endpoint->getSubscriber('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "subscriber_uid": "ll381bxshm01e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" } }

This endpoint retrieves the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber to retrieve belongs.
SUBSCRIBER-UNIQUE-IDyesSubscriber unique id to retrieve.

Search by email

// SEARCH BY EMAIL $response = $endpoint->emailSearch('LIST-UNIQUE-ID', '[email protected]'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "subscriber_uid": "sf449a4k7n193", "status": "confirmed", "date_added": "2021-02-20 17:26:16" } }

This endpoint searches a subscriber by his email within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber to retrieve belongs.

Query Parameters

ParameterRequiredDescription
emailyesSubscriber email to retrieve.

Search by email in all lists

// SEARCH BY EMAIL IN ALL LISTS $response = $endpoint->emailSearchAllLists('[email protected]'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "records": [ { "subscriber_uid": "sf449a4k7n193", "email": "[email protected]", "status": "confirmed", "source": "import", "ip_address": "", "list": { "list_uid": "cn417nrhmv922", "display_name": "Testing list", "name": "Testing list #4" }, "date_added": "2021-02-20 17:26:16" } ], "count": 1, "current_page": 1, "next_page": null, "prev_page": null, "total_pages": 1 } }

This endpoint searches a subscriber by his email within the all lists.

HTTP Request

GET API-URL/lists/subscribers/search-by-email-in-all-lists

Query Parameters

ParameterRequiredDescription
emailyesSubscriber email to retrieve.

Search by custom fields in a list

// SEARCH BY CUSTOM FIELDS IN A LIST $response = $endpoint->searchByCustomFields('LIST-UNIQUE-ID', [ 'EMAIL' => '[email protected]' ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "subscriber_uid": "ll381bxshm01e", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "status": "unsubscribed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:18" } }

This endpoint searches a subscriber by his custom fields values within a list given by LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-custom-fields

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList to search in.

Query Parameters

ParameterRequired/DefaultDescription
arrayyesArray of custom fields {'CUSTOM_FIELD' => 'VALUE'}
page1Current page to retrieve.
per_page10Items per page to retrieve.

Search by status

// SEARCH BY STATUS $response = $endpoint->searchByStatus('LIST-UNIQUE-ID', 'confirmed', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint search for the subscribers having a certain status within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterRequiredDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
statusyesSubscribers status to retrieve.

Get blacklisted subscribers

// Get only the blacklisted subscribers $response = $endpoint->getBlacklistedSubscribers('LIST-UNIQUE-ID', 'active', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "blacklisted", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "blacklisted", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "blacklisted", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint returns all the subscribers with the status blacklisted within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterRequiredDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
statusblacklistedThe blacklisted status value.

Get confirmed subscribers

// GET ALL ITEMS $response = $endpoint->getConfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "confirmed", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint retrieves all the confirmed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
statusconfirmedThe confirmed status value

Get unconfirmed subscribers

// GET ALL ITEMS $response = $endpoint->getUnconfirmedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unconfirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unconfirmed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unconfirmed", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint retrieves all the unconfirmed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
statusunconfirmedThe unconfirmed status value

Get unsubscribed subscribers

// GET ALL ITEMS $response = $endpoint->getUnsubscribedSubscribers('LIST-UNIQUE-ID', $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "subscriber_uid": "jl349100yda86", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unsubscribed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unsubscribed", "ip_address": "", "date_added": "2021-02-20 17:26:15" }, { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "", "LNAME": "", "source": "import", "status": "unsubscribed", "ip_address": "", "date_added": "2021-02-20 17:26:14" } ] } }

This endpoint retrieves all the unsubscribed subscribers of a list.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesThe list unique identifier for which we retrieve the subscribers

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
statusunsubscribedThe unsubscribe status value

Create a subscriber

// ADD SUBSCRIBER $response = $endpoint->create('LIST-UNIQUE-ID', [ 'EMAIL' => '[email protected]', // the confirmation email will be sent!!! Use valid email address 'FNAME' => 'John', 'LNAME' => 'Doe' ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "data": { "record": { "subscriber_uid": "bm421c3lwe043", "email": "[email protected]", "ip_address": "5.13.134.200", "source": "api", "date_added": { "expression": "NOW()", "params": {} } } } }

This endpoint creates a subscriber

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique identifier.

POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the custom fields {name => value}. The EMAIL key is required.

Create subscribers in bulk

// ADD SUBSCRIBERS IN BULK (since Labnify 1.8.1) $response = $endpoint->createBulk('LIST-UNIQUE-ID', [ [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe' ], [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe' ], [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe' ] ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "data": { "records": [ { "data": { "subscriber_uid": "kw647a5n8l516", "EMAIL": "[email protected]", "FNAME": "John1", "LNAME": "Doe1", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:14" } }, { "data": { "subscriber_uid": "fy287b32cs054", "EMAIL": "[email protected]", "FNAME": "John2", "LNAME": "Doe2", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:14" } }, { "data": { "subscriber_uid": "vo155s4b0d0ad", "EMAIL": "[email protected]", "FNAME": "John3", "LNAME": "Doe3", "status": "confirmed", "source": "import", "ip_address": "", "date_added": "2021-02-20 17:26:14" } } ] } }

This endpoint creates subscribers in bulk

HTTP Request

POST API-URL/lists/LIST-UNIQUE-ID/subscribers/bulk

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique identifier.

POST Parameters

ParameterTypeRequiredDescription
arraystringyesArray of arrays with the custom fields {name => value}. The EMAIL key is required.

Update a subscriber

// UPDATE EXISTING SUBSCRIBER $response = $endpoint->update('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe Updated' ]); // DISPLAY RESPONSE echo '<hr />'; echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "subscriber_uid": "kw647a5n8l516", "email": "[email protected]", "ip_address": "10.10.10.10", "source": "api", "date_added": "2021-02-20 17:26:14" } } }

This endpoint update the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given list LIST-UNIQUE-ID.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

URL Segments

ParameterRequiredDescription
LIST-UNIQUE-IDyesList unique identifier
SUBSCRIBER-UNIQUE-IDyesSubscriber unique identifier

PUT Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the custom fields {name => value} to be updated.

Update a subscriber by email

// UPDATE EXISTING SUBSCRIBER BY EMAIL $response = $endpoint->updateByEmail('LIST-UNIQUE-ID', '[email protected]', [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe Updated' ]); // DISPLAY RESPONSE echo '<hr />'; echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "data": { "record": { "subscriber_uid": "kw647a5n8l516", "email": "[email protected]", "ip_address": "10.10.10.10", "source": "api", "date_added": "2021-02-20 17:26:14" } } }

This endpoint update the subscriber with the given EMAIL from the given list LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique identifier
SUBSCRIBER-UNIQUE-IDyesFound subscriber unique identifier

GET/PUT Parameters

ParameterTypeRequiredDescription
EMAILstringyesEmail to be searched
dataarrayyesArray with the custom fields {name => value} to be updated.

Create/Update a subscriber

// CREATE / UPDATE EXISTING SUBSCRIBER $response = $endpoint->createUpdate('LIST-UNIQUE-ID', [ 'EMAIL' => '[email protected]', 'FNAME' => 'John', 'LNAME' => 'Doe Updated Second time' ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "data": { "record": { "subscriber_uid": "kw647a5n8l516", "email": "[email protected]", "ip_address": "10.10.10.10", "source": "api", "date_added": "2021-02-20 17:26:14" } } }

This endpoint update the subscriber if exists and created it otherwise, from the given list LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

POST API-URL/lists/LIST-UNIQUE-ID/subscribers

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique identifier
SUBSCRIBER-UNIQUE-IDyesFound subscriber unique identifier

GET/PUT/POST Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the custom fields {name => value} to be updated.
EMAILstringyesEmail to be searched

Unsubscribe a subscriber

// UNSUBSCRIBE existing subscriber, no email is sent, unsubscribe is silent $response = $endpoint->unsubscribe('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint unsubscribes the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-IDyesSubscriber unique id to unsubscribe.

Unsubscribe a subscriber by email address

// UNSUBSCRIBE existing subscriber by email address, no email is sent, unsubscribe is silent $response = $endpoint->unsubscribeByEmail('LIST-UNIQUE-ID', '[email protected]'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint unsubscribes the subscriber with the given EMAIL from the given LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

PUT API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID/unsubscribe

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-IDyesSubscriber unique id to unsubscribe.

Query Parameters

ParameterRequiredDescription
EMAILyesSubscriber email to unsubscribe.

Unsubscribe a subscriber by email address from all the lists

// UNSUBSCRIBE existing subscriber from all lists, no email is sent, unsubscribe is silent $response = $endpoint->unsubscribeByEmailFromAllLists('[email protected]'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint unsubscribes the subscriber with the given EMAIL from all the lists.

HTTP Request

PUT API-URL/lists/subscribers/unsubscribe-by-email-from-all-lists

PUT Parameters

ParameterRequiredDescription
EMAILyesSubscriber email to unsubscribe.

Delete one subscriber

// DELETE SUBSCRIBER, no email is sent, delete is silent $response = $endpoint->delete('LIST-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint deletes the subscriber with the given SUBSCRIBER-UNIQUE-ID from the given LIST-UNIQUE-ID.

HTTP Request

DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-IDyesSubscriber unique id to delete.

Delete by email

// DELETE SUBSCRIBER by email address, no email is sent, delete is silent $response = $endpoint->deleteByEmail('LIST-UNIQUE-ID', '[email protected]'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint deletes a subscriber by his email within the list having the LIST-UNIQUE-ID.

HTTP Request

GET API-URL/lists/LIST-UNIQUE-ID/subscribers/search-by-email

DELETE API-URL/lists/LIST-UNIQUE-ID/subscribers/SUBSCRIBER-UNIQUE-ID

URL Segments

SegmentRequiredDescription
LIST-UNIQUE-IDyesList unique id to which the subscriber belongs.
SUBSCRIBER-UNIQUE-IDyesSubscriber unique id to delete.

GET Parameters

ParameterRequiredDescription
emailyesSubscriber email to retrieve.

Campaigns

Campaigns endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\Campaigns();

Get all campaigns

// GET ALL ITEMS $response = $endpoint->getCampaigns($pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo "<pre>"; print_r($response->body); echo "</pre>";

The above command returns an object structured like this JSON:

[ { "status": "success", "data": { "count": "12", "total_pages": 2, "current_page": 1, "next_page": 2, "prev_page": null, "records": [ { "campaign_uid": "og943e5q6e158", "campaign_id": "12", "name": "My API Campaign UPDATED #3", "status": "sent", "group": [] }, { "campaign_uid": "gp5420ve90f3e", "campaign_id": "13", "name": "My API Campaign UPDATED #2", "status": "sent", "group": [] }, { "campaign_uid": "hv4163y076d84", "campaign_id": "14", "name": "My API Campaign UPDATED #1", "status": "sent", "group": [] }, { "campaign_uid": "xk906nd8fn506", "campaign_id": "15", "name": "My API Campaign UPDATED", "status": "sent", "group": [] }, { "campaign_uid": "eh477yfos0258", "campaign_id": "16", "name": "API campaing #1", "status": "draft", "group": [] }, { "campaign_uid": "db516xtc45237", "campaign_id": "17", "name": "API campaing #2", "status": "draft", "group": [] }, { "campaign_uid": "ld526wjke1ff4", "campaign_id": "18", "name": "API campaing #1", "status": "draft", "group": [] }, { "campaign_uid": "bx831rctawf92", "campaign_id": "19", "name": "API campaing", "status": "paused", "group": [] }, { "campaign_uid": "tk459h475l8ef", "campaign_id": "20", "name": "Test #1", "status": "sent", "group": [] }, { "campaign_uid": "go896lnslz8ae", "campaign_id": "21", "name": "Test", "status": "sent", "group": [] } ] } } ]

This endpoint retrieves all the campaigns.

HTTP Request

GET API-URL/campaigns

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.
list_uidYou can get only the campaigns for the list with the specified unique id

Get one campaign

// GET ONE ITEM $response = $endpoint->getCampaign('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "campaign_uid": "og943e5q6e158", "campaign_id": "12", "name": "My API Campaign UPDATED #3", "type": "regular", "from_name": "John Doe", "from_email": "[email protected]", "to_name": "[EMAIL]", "reply_to": "[email protected]", "subject": "Hey, i am testing the campaigns via API", "status": "sent", "date_added": "2\/24\/21, 11:38 PM", "send_at": "2\/24\/21, 11:39 PM", "list": { "list_uid": "ra5026psrjeb5", "name": "Testing list", "subscribers_count": 0 }, "segment": [], "group": [] } } }

This endpoint retrieves the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to retrieve.

Create a campaign

// CREATE CAMPAIGN $response = $endpoint->create([ 'name' => 'My API Campaign', // required 'type' => 'regular', // optional: regular or autoresponder 'from_name' => 'John Doe', // required 'from_email' => '[email protected]', // required 'subject' => 'Hey, i am testing the campaigns via API', // required 'reply_to' => '[email protected]', // required 'send_at' => date('Y-m-d H:i:s', strtotime('+10 hours')), // required, this will use the timezone which customer selected 'list_uid' => 'LIST-UNIQUE-ID', // required 'segment_uid' => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down // optional block, defaults are shown 'options' => [ 'url_tracking' => 'no', // yes | no 'json_feed' => 'no', // yes | no 'xml_feed' => 'no', // yes | no 'plain_text_email' => 'yes',// yes | no 'email_stats' => null, // a valid email address where we should send the stats after campaign done // - if autoresponder uncomment bellow: //'autoresponder_event' => 'AFTER-SUBSCRIBE', // AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN //'autoresponder_time_unit' => 'hour', // minute, hour, day, week, month, year //'autoresponder_time_value' => 1, // 1 hour after event //'autoresponder_open_campaign_id' => 1, // INT id of campaign, only if event is AFTER-CAMPAIGN-OPEN, // - if this campaign is advanced recurring, you can set a cron job style frequency. // - please note that this applies only for regular campaigns. //'cronjob' => '0 0 * * *', // once a day //'cronjob_enabled' => 1, // 1 or 0 ], // required block, archive or template_uid or content => required. 'template' => [ //'archive' => file_get_contents(__DIR__ . '/template-example.zip'), //'template_uid' => 'TEMPLATE-UNIQUE-ID', 'content' => file_get_contents(__DIR__ . '/template-example.html'), 'inline_css' => 'no', // yes | no 'plain_text' => null, // leave empty to auto generate 'auto_plain_text' => 'yes', // yes | no ], ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "campaign_uid": "hv4163y076d84" }

This endpoint creates a campaign

HTTP Request

POST API-URL/campaigns

POST Parameters

ParameterTypeRequiredDescription
campaignarrayyesArray with the email details.

Campaign block

ParameterTypeRequiredDescription
namestringyesCampaign name.
typestringnoCampaign type: regular or autoresponder. Default is regular.
from_namestringyesThe campaign from name
from_emailstringyesThe campaign from email address
subjectstringyesThe campaign subject
from_namestringyesThe subscriber for which we record the bounce
reply_tostringyesThe campaign reply to email address
send_atdatetime (Y-m-d H:i:s)yesThis will use the timezone which customer selected
list_uidstringyesThe list uid to which this campaign will be sent
segment_uidstringnoNarrow down the campaign recipients
templatearrayyesThe campaign template object block. Archive or template_uid or content => required
optionsarraynoThe campaign optional block, defaults are shown

Template block

ParameterTypeRequiredDescription
archivefilePathyesTemplate file zip location
template_uidstringyesTemplate unique id from Labnify
contentstringyesTemplate content
inline_cssyes/noyesAccept inline css
plain_textnull/stringnoSend null to autogenerate as default
auto_plain_textyes/noyesGenerate plain text template

Options block

ParameterTypeRequiredDescription
url_trackingyes/nonoEnable/Disable url tracking
json_feedyes/nonoEnable/Disable json feed
xml_feedyes/nonoEnable/Disable xml feed
plain_text_emailyes/nonoEnable/Disable the plain text email
email_statsstring/nullnoA valid email address where the stats will be sent
autoresponder_eventstringnoPossible values: AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
autoresponder_eventstringnoPossible values: AFTER-SUBSCRIBE or AFTER-CAMPAIGN-OPEN
autoresponder_time_unitstringnoPossible values: minute, hour, day, week, month, year
autoresponder_time_valueintegernoThe unit time value
autoresponder_time_valueintegernoThe unit time value
autoresponder_open_campaign_idintegernoId of the campaign, only if event is AFTER-CAMPAIGN-OPEN
cronjobstringnoIf this campaign is advanced recurring, you can set a cron job style frequency
cronjob_enabledintegernoPossible values 1 or 0

Update a campaign

// UPDATE CAMPAIGN $response = $endpoint->update('CAMPAIGN-UNIQUE-ID', [ 'name' => 'My API Campaign UPDATED', // optional at update 'from_name' => 'John Doe', // optional at update 'from_email' => '[email protected]', // optional at update 'subject' => 'Hey, i am testing the campaigns via API', // optional at update 'reply_to' => '[email protected]', // optional at update 'send_at' => date('Y-m-d H:i:s', strtotime('+1 hour')), //optional at update, this will use the timezone which customer selected 'list_uid' => 'LIST-UNIQUE-ID', // optional at update 'segment_uid' => 'SEGMENT-UNIQUE-ID',// optional, only to narrow down // optional block, defaults are shown 'options' => [ 'url_tracking' => 'no', // yes | no 'json_feed' => 'no', // yes | no 'xml_feed' => 'no', // yes | no 'plain_text_email' => 'yes',// yes | no 'email_stats' => null, // a valid email address where we should send the stats after campaign done ], // optional block at update, archive or template_uid or content => required. 'template' => [ //'archive' => file_get_contents(__DIR__ . '/template-example.zip'), //'template_uid' => 'TEMPLATE-UNIQUE-ID', 'content' => file_get_contents(__DIR__ . '/template-example.html'), 'inline_css' => 'no', // yes | no 'plain_text' => null, // leave empty to auto generate 'auto_plain_text' => 'yes', // yes | no ], ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint update the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to update.

POST Parameters

Same as for the create campaign call.

Copy a campaign

// Copy CAMPAIGN $response = $endpoint->copy('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success", "campaign_uid": "hv4163y076d84" }

This endpoint copy the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/copy

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to copy.

Pause/Unpause a campaign

// Pause/Unpause CAMPAIGN $response = $endpoint->pauseUnpause('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "campaign": { "status": "sending" } }

This endpoint pause/unpause the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/pause-unpause

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to pause/unpause.

Mark a campaign as SENT

// Mark CAMPAIGN as sent $response = $endpoint->markSent('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "campaign": { "status": "sent" } }

This endpoint mark as SENT the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

PUT API-URL/campaigns/CAMPAIGN-UNIQUE-ID/mark-sent

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to mark as sent.

Delete a campaign

// Delete CAMPAIGN $response = $endpoint->delete('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status":"success" }

This endpoint will delete the campaign with the given CAMPAIGN-UNIQUE-ID.

HTTP Request

DELETE API-URL/campaigns/CAMPAIGN-UNIQUE-ID

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to delete.

Get stats of a campaign

// GET STATS $response = $endpoint->getStats('CAMPAIGN-UNIQUE-ID'); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "campaign_status": "sent", "subscribers_count": 0, "processed_count": 0, "delivery_success_count": 0, "delivery_success_rate": 0, "delivery_error_count": 0, "delivery_error_rate": 0, "opens_count": 0, "opens_rate": 0, "unique_opens_count": 0, "unique_opens_rate": 0, "clicks_count": 0, "clicks_rate": 0, "unique_clicks_count": 0, "unique_clicks_rate": 0, "unsubscribes_count": 0, "unsubscribes_rate": 0, "complaints_count": 0, "complaints_rate": 0, "bounces_count": 0, "bounces_rate": 0, "hard_bounces_count": 0, "hard_bounces_rate": 0, "soft_bounces_count": 0, "soft_bounces_rate": 0, "internal_bounces_count": 0, "internal_bounces_rate": 0 } }

This endpoint retrieves the campaign stats the given CAMPAIGN-UNIQUE-ID.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/stats

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to retrieve.

Campaigns tracking

Campaigns tracking endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\CampaignsTracking();

Track subscriber click for campaign

// Track subscriber click for campaign click $response = $endpoint->trackUrl('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', 'URL-HASH'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": {} }

This endpoint set a campaign tracking url click action.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UID/track-url/SUBSCRIBER-UNIQUE-ID/URL-HASH

URL Segments

SegmentRequiredDescription
CAMPAIGN-UIDYesCampaign unique identifier.
SUBSCRIBER-UNIQUE-IDYesSubscriber unique identifier.
URL-HASHYesThe url hash which the subscriber clicked.

Track subscriber open

// Track subscriber open for campaign $response = $endpoint->trackOpening('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": {} }

This endpoint sets the track campaign open for a certain subscriber.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UID/track-opening/SUBSCRIBER-UID

URL Segments

SegmentRequiredDescription
CAMPAIGN-UIDYesCampaign unique identifier.
SUBSCRIBER-UNIQUE-IDYesSubscriber unique identifier.

Track subscriber unsubscribe

// Track subscriber unsubscribe for campaign $response = $endpoint->trackUnsubscribe('CAMPAIGN-UNIQUE-ID', 'SUBSCRIBER-UNIQUE-ID', [ 'ip_address' => '123.123.123.123', 'user_agent' => 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36', 'reason' => 'Reason for unsubscribe!', ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": {} }

This endpoint sets the track campaign unsubscribe for a certain subscriber.

HTTP Request

POST API-URL/campaigns/CAMPAIGN-UID/track-unsubscribe/SUBSCRIBER-UID

URL Segments

SegmentRequiredDescription
CAMPAIGN-UIDYesCampaign unique identifier.
SUBSCRIBER-UNIQUE-IDYesSubscriber unique identifier.

POST Parameters

ParameterRequiredDescription
ip_addressNoIP address from which the subscriber unsubscribes
user_agentNoSubscriber user agent
reasonNoUnsubscribe reason

Campaign bounces

Campaigns bounces endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\CampaignBounces();

Get all bounces

// GET ALL ITEMS $response = $endpoint->getBounces('CAMPAIGN-UNIQUE-ID, $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo "<pre>"; print_r($response->body); echo "</pre>";

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "1", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "message": "5.1.1 : Recipient address rejected: User unknown in virtual mailbox table", "processed": "no", "bounce_type": "hard", "subscriber": { "subscriber_uid": "xq907cko16da3", "email": "[email protected]" } } ] } }

This endpoint retrieves all the bounces of a campaign.

HTTP Request

GET API-URL/campaigns/CAMPAIGN-UNIQUE-ID/bounces

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to retrieve the bounce.

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Create a bounce

// CREATE BOUNCE $response = $endpoint->create('CAMPAIGN-UNIQUE-ID', [ 'message' => 'The reason why this email bounced', // max 250 chars 'bounce_type' => 'hard', // hard, soft or internal 'subscriber_uid' => 'SUBSCRIBER-UNIQUE-ID' // 13 chars unique subscriber identifier ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "message": "The reason why this email bounced", "processed": "no", "bounce_type": "hard", "subscriber": { "subscriber_uid": "fo428vd43x832", "email": "[email protected]" } } } }

This endpoint creates a campaign bounce

HTTP Request

POST API-URL/campaigns/CAMPAIGN-UNIQUE-ID/bounces

URL Segments

SegmentRequiredDescription
CAMPAIGN-UNIQUE-IDyesCampaign unique id to create the bounce.

POST Parameters

ParameterRequiredDescription
messageyesThe bounce message to be recorded.
bounce_typeyesBounce type (hard, soft or internal).
subscriber_uidyesThe subscriber for which we record the bounce

Countries

Countries endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\Countries();

Get all countries

// GET ALL ITEMS $response = $endpoint->getCountries($pageNumber = 23, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "240", "total_pages": 24, "current_page": 23, "next_page": 24, "prev_page": 22, "records": [ { "country_id": "218", "name": "Tuvalu", "code": "TV" }, { "country_id": "219", "name": "Uganda", "code": "UG" }, { "country_id": "220", "name": "Ukraine", "code": "UA" }, { "country_id": "221", "name": "United Arab Emirates", "code": "AE" }, { "country_id": "222", "name": "United Kingdom", "code": "GB" }, { "country_id": "223", "name": "United States", "code": "US" }, { "country_id": "224", "name": "United States Minor Outlying Islands", "code": "UM" }, { "country_id": "225", "name": "Uruguay", "code": "UY" }, { "country_id": "226", "name": "Uzbekistan", "code": "UZ" }, { "country_id": "227", "name": "Vanuatu", "code": "VU" } ] } }

This endpoint retrieves all the countries.

HTTP Request

GET API-URL/countries

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get all zones of a country

// get country zones $response = $endpoint->getZones(COUNTRY-ID, $pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "65", "total_pages": 7, "current_page": 1, "next_page": 2, "prev_page": null, "records": [ { "zone_id": "3613", "name": "Alabama", "code": "AL" }, { "zone_id": "3614", "name": "Alaska", "code": "AK" }, { "zone_id": "3615", "name": "American Samoa", "code": "AS" }, { "zone_id": "3616", "name": "Arizona", "code": "AZ" }, { "zone_id": "3617", "name": "Arkansas", "code": "AR" }, { "zone_id": "3618", "name": "Armed Forces Africa", "code": "AF" }, { "zone_id": "3619", "name": "Armed Forces Americas", "code": "AA" }, { "zone_id": "3620", "name": "Armed Forces Canada", "code": "AC" }, { "zone_id": "3621", "name": "Armed Forces Europe", "code": "AE" }, { "zone_id": "3622", "name": "Armed Forces Middle East", "code": "AM" } ] } }

This endpoint retrieves all the zones of a country.

HTTP Request

GET API-URL/countries/COUNTRY-ID/zones

URL Segments

SegmentRequiredDescription
COUNTRY-IDYesCountry Labnify ID to retrieve zones for.

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Customers

Customers endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\Customers();

Create a customer

// CREATE CUSTOMER $response = $endpoint->create([ 'customer' => [ 'first_name' => 'John', 'last_name' => 'Doe', 'email' => '[email protected]', 'password' => 'superDuperPassword', 'timezone' => 'UTC', 'birthDate' => 'Y-m-d' ], // company is optional, unless required from app settings 'company' => [ 'name' => 'John Doe LLC', 'country' => 'United States', // see the countries endpoint for available countries and their zones 'zone' => 'New York', // see the countries endpoint for available countries and their zones 'city' => 'Brooklyn', 'zip_code' => 11222, 'address_1'=> 'Some Address', 'address_2'=> 'Some Other Address', ], ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "customer_uid": "wc149l7wdm9be" }

This endpoint creates a customer

HTTP Request

POST API-URL/customers

POST Parameters

ParameterTypeRequiredDescription
customerarrayyesThe array with the customer details.
companyarraynoThe array with the company details if required by the Labnify settings.

Customer block

ParameterTypeRequiredDescription
first_namestringyesCustomer first name
last_namestringyesCustomer last name
emailstringyesCustomer email
passwordstringyesCustomer password
timezonestringyesCustomer timezone(i.e. UTC)
birthDatestringyesCustomer birth date (YYYY-MM-DD)

Company block

ParameterTypeRequiredDescription
namestringyesCompany name
countrystringyesCompany country (See the Countries endpoint for available countries and zones)
zonestringyesCompany zone
citystringyesCompany city
zip_codestringyesCompany zipcode
address_1stringyesCompany address
address_2stringyesCompany another address

Templates

Templates endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\Templates();

Get all templates

// GET ALL ITEMS $response = $endpoint->getTemplates($pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "records": [ { "template_uid": "xxxxxxxxx", "name": "portfolio_html (1)", "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png" } ] } }

This endpoint retrieves all the templates.

HTTP Request

GET API-URL/templates

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one template

// GET ONE ITEM $response = $endpoint->getTemplate('TEMPLATE-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "name": "portfolio_html (1)", "content": "HTML content...", "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png" } } }

This endpoint retrieves the template with the given TEMPLATE-UNIQUE-ID.

HTTP Request

GET API-URL/templates/TEMPLATE-UNIQUE-ID

URL Segments

SegmentRequiredDescription
TEMPLATE-UNIQUE-IDyesTemplate unique id which to retrieve.

Search templates

// Search ALL ITEMS (available from Labnify 1.4.4) $response = $endpoint->searchTemplates($pageNumber = 1, $perPage = 10, [ 'name' => 'my template name' ]); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "records": [ { "name": "portfolio_html (1)", "content": "HTML content...", "screenshot": "https:\/\/domain.com\/frontend\/assets\/gallery\/ew055sq9tn97e\/img_ytStill.png" } ] } }

This endpoint retrieves the templates based on the filter keys values.

HTTP Request

GET API-URL/templates

Query Parameters

ParameterTypeRequired/DefaultDescription
pageint1Current page to retrieve.
per_pageint10Items per page to retrieve.
filtersarrayyesIndexed array having template attributes as keys.(i.e.: name )

Create a template

// CREATE A NEW TEMPLATE $rand = rand(); $response = $endpoint->create([ 'name' => 'My API template ' . $rand, 'content' => file_get_contents(__DIR__ . '/template-example.html'), //'archive' => file_get_contents(__DIR__ . '/template-example.zip'), 'inline_css' => 'no',// yes|no ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "template_uid": "jo441taeq281e" }

This endpoint creates a template.

HTTP Request

POST API-URL/templates

POST Parameters

ParameterTypeRequiredDescription
templatearrayyesArray with the template details.

Data block - required

ParameterTypeRequiredDescription
namestringyesTemplate name
contentstringyesThe template content
archivestringnoZip archive name on the disk. This can be used when not using the plain content key
inline_cssYes/NonoAllow/disallow inline css

Update a template

// UPDATE A TEMPLATE $response = $endpoint->update('TEMPLATE-UNIQUE-ID', [ 'name' => 'My API template - updated' . $rand, 'content' => file_get_contents(__DIR__ . '/template-example.html'), //'archive' => file_get_contents(__DIR__ . '/template-example.zip'), 'inline_css' => 'no',// yes|no ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success" }

This endpoint updates a template.

HTTP Request

PUT API-URL/templates/TEMPLATE-UNIQUE-ID

URL Segments

SegmentRequiredDescription
TEMPLATE-UNIQUE-IDyesTemplate unique identifier

PUT Parameters

ParameterTypeRequiredDescription
dataarrayyesArray with the template details. See the create section for details

Delete a template

// delete template $response = $endpoint->delete('TEMPLATE-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success" }

This endpoint will delete the template with the given TEMPLATE-UNIQUE-ID.

HTTP Request

DELETE API-URL/templates/TEMPLATE-UNIQUE-ID

URL Segments

SegmentRequiredDescription
TEMPLATE-UNIQUE-IDyesTemplate unique id to delete.

Transactional Emails

Transactional emails endpoint

// CREATE THE ENDPOINT $endpoint = new EmsApi\Endpoint\TransactionalEmails();

Get all transactional emails

// GET ALL ITEMS $response = $endpoint->getEmails($pageNumber = 1, $perPage = 10); // DISPLAY RESPONSE echo '<pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "count": "3", "total_pages": 1, "current_page": 1, "next_page": null, "prev_page": null, "records": [ { "email_uid": "pc939rqfc16c5", "customer_id": "1", "to_email": "[email protected]", "to_name": "John Doe", "from_email": "[email protected]", "from_name": "Jane Doe", "reply_to_email": "[email protected]", "reply_to_name": "Jane Doe", "subject": "This is the email subject", "body": "<strong>Hello world!<\/strong>", "plain_text": "HELLO WORLD!", "priority": "5", "retries": "0", "max_retries": "3", "send_at": "2021-02-25 11:00:58", "fallback_system_servers": "no", "status": "sent", "date_added": "2021-02-25 11:01:00", "last_updated": "2021-02-25 11:02:01", "attachments": [] }, { "email_uid": "ja646gs7w3d09", "customer_id": "1", "to_email": "[email protected]", "to_name": "John Doe", "from_email": "[email protected]", "from_name": "Jane Doe", "reply_to_email": "[email protected]", "reply_to_name": "Jane Doe", "subject": "This is the email subject", "body": "<strong>Hello world!<\/strong>", "plain_text": "HELLO WORLD!", "priority": "5", "retries": "0", "max_retries": "3", "send_at": "2021-02-23 08:57:13", "fallback_system_servers": "no", "status": "sent", "date_added": "2021-02-23 08:57:18", "last_updated": "2021-02-23 08:58:01", "attachments": [] }, { "email_uid": "zd716gnx0y1a1", "customer_id": "1", "to_email": "[email protected]", "to_name": "John Doe", "from_email": "[email protected]", "from_name": "Jane Doe", "reply_to_email": "[email protected]", "reply_to_name": "Jane Doe", "subject": "This is the email subject", "body": "<strong>Hello world!<\/strong>", "plain_text": "HELLO WORLD!", "priority": "5", "retries": "0", "max_retries": "3", "send_at": "2021-02-23 08:53:10", "fallback_system_servers": "no", "status": "sent", "date_added": "2021-02-23 08:53:15", "last_updated": "2021-02-23 08:54:01", "attachments": [] } ] } }

This endpoint retrieves all the transactional emails.

HTTP Request

GET API-URL/transactional-emails

Query Parameters

ParameterDefaultDescription
page1Current page to retrieve.
per_page10Items per page to retrieve.

Get one transactional email

// GET ONE ITEM $response = $endpoint->getEmail('EMAIL-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "data": { "record": { "email_uid": "pc939rqfc16c5", "customer_id": "1", "to_email": "[email protected]", "to_name": "John Doe", "from_email": "[email protected]", "from_name": "Jane Doe", "reply_to_email": "[email protected]", "reply_to_name": "Jane Doe", "subject": "This is the email subject", "body": "<strong>Hello world!<\/strong>", "plain_text": "HELLO WORLD!", "priority": "5", "retries": "0", "max_retries": "3", "send_at": "2021-02-25 11:00:58", "fallback_system_servers": "no", "status": "sent", "date_added": "2021-02-25 11:01:00", "last_updated": "2021-02-25 11:02:01", "attachments": [ { "type": "application/pdf", "name": "filename", "data": "Email attachment content blob" } ] } } }

This endpoint retrieves the transactional email with the given EMAIL-UNIQUE-ID.

HTTP Request

GET API-URL/transactional-emails/EMAIL-UNIQUE-ID

URL Segment

SegmentRequiredDescription
EMAIL-UNIQUE-IDyesEmail unique id which to retrieve.

Create a transactional email

// CREATE A NEW EMAIL $response = $endpoint->create([ 'to_name' => 'John Doe', // required 'to_email' => '[email protected]', // required 'from_name' => 'Jane Doe', // required 'from_email' => '[email protected]', // optional 'reply_to_name' => 'Jane Doe', // optional 'reply_to_email' => '[email protected]', // optional 'subject' => 'This is the email subject', // required 'body' => '<strong>Hello world!</strong>', // required 'plain_text' => 'Hello world!', // optional, will be autogenerated if missing 'send_at' => date('Y-m-d H:i:s'), // required, UTC date time in same format!, 'attachments' => [ [ 'type' => 'image/png', 'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.png'), 'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.png')), ], [ 'type' => 'image/jpeg', 'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.jpg'), 'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.jpg')), ], [ 'type' => 'application/pdf', 'name' => basename(__DIR__ . '/PATH_TO_YOUR_FILE/file.pdf'), 'data' => base64_encode((string)file_get_contents(__DIR__ . '/PATH_TO_YOUR_FILE/file.pdf')), ], ] ]); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success", "email_uid": "vy348j4jqn1d1" }

This endpoint creates a transactional email.

HTTP Request

POST API-URL/transactional-emails

POST Parameters

ParameterTypeRequiredDescription
emailarrayyesArray with the email details.

Data block - required

ParameterTypeRequiredDescription
to_namestringyesRecipient name
to_emailstringyesRecipient email
from_namestringyesSender name
subjectstringyesEmail subject
bodystringyesEmail body
send_atdatetimeyesUTC datetime (Y-m-d H:i:s format)
plain_textstringnoEmail plain text. Auto generated if missing
from_emailstringnoSender email
reply_to_namestringnoReply to name
reply_to_emailstringnoReply to email
attachmentsarraynoArray of attachments in the form ['type', 'name', 'data']

Delete a transactional email

// delete email $response = $endpoint->delete('EMAIL-UNIQUE-ID'); // DISPLAY RESPONSE echo '<hr /><pre>'; print_r($response->body); echo '</pre>';

The above command returns an object structured like this JSON:

{ "status": "success" }

This endpoint will delete the transactional email with the given EMAIL-UNIQUE-ID.

HTTP Request

DELETE API-URL/transactional-emails/EMAIL-UNIQUE-ID

URL Segments

SegmentRequiredDescription
EMAIL-UNIQUE-IDyesEmail unique id to delete.

See more on API below..

Bulk Email Verification API Documentation

This bulk email verification API is useful to all Labnify Users especially if you wish to resell our bulk email verification service via API.

How to become a user or reseller for Labnify’s VeriPurge

Step. 1. You need to be a customer or subscriber with a minimum of $100 in your Labnify wallet.

Step. 2. Become a bulk email verification API user or reseller by applying here.

Pricing: $0.0005 per email submitted for verification via API. Minimum emails you can clean per API-based email verification request is 20,000 emails; maximum emails you can clean per API-based email verification request is 1 million emails.

______

 

API Documentation for Bulk Email Verification

Endpoint

URL: https://labnify.com/api/verification_api.php

Methods: POST

Authentication

Required: Yes

Parameters: user_id, api_key

Parameters

URL Parameters

user_id (string, required): Your user ID for authentication.

api_key (string, required): Your API key for authentication.

Body Parameters (JSON)

files_url (string, required): A URL or multiple URLs (comma-separated) pointing to

the files to be verified.

receiving_email (sting,required): Email address that will receive the

verified emails files through Email.

Headers

Content-Type: application/json

Methods

POST Method

Request

POST /api/verification_api.php?user_id=YOUR_USER_ID&api_key=YOUR_API_KEY

HTTP/1.1

Host: labnify.com

Content-Type: application/json

{

“files_url”: “URL1,URL2,URL3”,

“receiving_email”:”email_address”

}

Example

POST

/api/verification_api.php?user_id=1234&api_key=9ZgLOuk1EA5w93ymqKGOZy3wub4aEF

O2bdNI0UxTa1Qdtx0OsLzTaiPBC1xbzejH HTTP/1.1

Host: labnify.com

Content-Type: application/json

{

“files_url”:

“https://example.com/files/file1.csv,https://example.com/files/OTHER_FILE.csv

“,

“receiving_email”:”[email protected]

}

Examples

cURL Examples

POST Method

curl –location

‘https://labnify.com/api/verification_api.php?user_id=1234&api_key=9ZgLOuk1EA

5w93ymqKGOZy3wub4aEFO2bdNI0UxTa1Qdtx0OsLzTaiPBC1xbzejH’ \

–header ‘Content-Type: application/json’ \

–data ‘{

“files_url”:

“https://labnify.com/api/DECLAN.csv,https://labnify.com/api/OTHER_FILE.csv”,

“receiving_email”:”[email protected]

}’

Response

Successful Response

{

“status”: “success”,

“message”: “Verification completed successfully.”

}

Error Response

{

“status”: “error”,

“message”: “Invalid user_id or api_key.”

}

Notes

  • Ensure that the user_id and api_key are passed as URL parameters for authentication.
  • The files_url parameter can accept multiple URLs separated by commas.
  • receiving_email must be a valid Email address which is used to receive verified emails file.

 

License: all code samples are licensed under MIT license.

SCAM ALERT !!

LABNIFY.COM is the only official website under our brand name and logo. 

________

We do NOT accept payment through Skype, Telegram, WhatsApp, or Live chat, and neither do we trade crypto nor offer jobs. If anyone does these in the name of Labnify, it is impersonation. For details, see legal Terms.