SmartSender API V3.0 | User Retention Automation

SmartSender API v3.0#

With SmartSender API v3.0, you can sync email activity and campaign stats with your database, manage lists, create and edit Automation workflows, and test different calls and endpoints before pushing to production.

The SmartSender API is designed for developers, engineers, or anyone else who’s comfortable creating custom-coded solutions or integrating with RESTful APIs. If you think you may need some help integrating with the SmartSender API just contact our Technical Support Team by support@smartsender.io email.

Send Email#

To send transactional or triggered Email you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/mailer/...

INFOThe request body should contain a JSON with the message content.

Below you can find detailed information on usage of different methods to send Email messages with SmartSender.

Send A New Email#

To send a new Email you need to send POST request to the following URL

https://api.smartsender.io/v3/mailer/send

Request body

{
    "from": {
        "email": "user@senderexample.com",
        "name": "Sender Name"
    },
    "to": {
        "email": "user@recipientexample.com",
        "name": "Contact Name"
    },
    "replyTo": {
        "email": "support@senderexample.com",
        "name": "Support"
    },
    "subject": "Hello subject",
    "html": "Hello, World!",
    "text": "Hello, World!",
    "tags": [
        "mailerApiSend"
    ],
    "headers": {
        "X-Additional-Header": "additional-header-value"
    },
    "priority": 1
}

Parameters
from `'required'`	An array of sender information. You can use only domain name verified in your account.
	email `'required'`	The sender email address email
	name ‘optional’	Optional from name to be used
to `'required'`	An array of recipient information. You can send only one email at a time. If you need to send same message to 2 recipients then you need to send it twice to SmartSender API
	email `'required'`	The email address of the recipient
	name ‘optional’	The optional display name to use for the recipient
replyTo ‘optional’	An array of optional reply-to information. Email address used to compose the email’s Custom “Reply-To” header. If no reply-to address provided “From” will be used instead
	email `'required'`	The email address of the reply-to recipient
	name ‘optional’	The optional display name to use for the reply-to recipient.
subject `'required'`	The message subject
html `'required'`	The full HTML or text content to be sent
text ‘optional’	Optional plain text content to be sent. If no text version of the email is provided SmartSender will generate it from the html copy.
tags ‘optional’	An array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. You can add custom tags to your messages to get custom reports on specific messages (tag templates, campaigns, different types of emails or audience, etc). WARNING: A single tag – must not start with an underscore
headers ‘optional’	Optional extra headers to add to the message (most headers are allowed)
priority ‘optional’	Add priority parameter to the outgoing emails to avoid delivery delays for important messages due to large promo campaigns in queue. INFO Defaults: Priority 1 is default value. You can have up to 5 priority levels. Priority level over 5 will be rounded to 5.

Response:

{
   "result":true,
   "messageId":"5d914c3dd132d5f45a4e3670"
}

Return Value the sending results for a single recipient
messageId	The message unique identification number in SmartSender system. With this ID number you can get all the statistics on each sent message.
result	The sending status of the recipient:
	true	The message is accepted and queued
	false	The message is rejected

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the message.
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Maximum count of records per transaction is 100, current {n}”
	“from field must contain email and name fields”
	“email parameter at from field required”
	“Invalid RFC2822 email {email}”
	“name parameter at from field must be a stri
	“to field must contain email and name fields”
	“email parameter at to field required”
	“Invalid RFC2822 email {email}”
	“name parameter at to field must be a string”
	“replyTo field must contain email and name fields”
	“email parameter at replyTo field required”
	“Invalid RFC2822 email {email}”
	“name parameter at replyTo field mu st be a string”
	“Argument subject must be a non-empty s tring”
	“Argument html must be a non-empty string”
	“Argument text must be a string”
	“Argument tags must be an array”
	“tag name must be a non-empty string”
	“Argument headers must be an array with header-names as keys and header-values as values”
	“header name must be a non-empty string”
	“header value must be a non-empty string”
	“Argument priority must be an integer”
	“Argument priority must be between 1 and 5”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/mailer/send';

$body        = json_encode([
    'from'     => [
        'email'    => 'user@senderexample.com',
        'name'     => 'Sender name',
    ],
    'to'       => [
        'email'    => 'user@recipientexample.com',
        'name'     => 'Recipient name',
    ],
    'replyTo'  => [
        'email'    => 'support@senderexample.com',
        'name'     => 'Support',
    ],
    'subject'  => 'Hello subject',
    'html'     => 'Hello, World!',
    'text'     => 'Hello, World!',
    'tags'     => [
       'mailerApiSend',
    ],
       'headers'   => [
       'X-Additional-Header' => 'additional-header-value',
    ],
    'priority' => 1,
]);

/**
* Documentation Example
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;
*/

/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "Access-Token: $accessToken",
 'Content-Type: application/json',
 'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

Send Triggered Email#

To send a new triggered email you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/mailer/trigger

Request body:

{
 "contactListId": "YOUR_CONTACT_LIST_ID",
 "contact": "user@example.com",
 "templateId": "YOUR_TEMPLATE_ID",
 "tags": [
    "triggerTag"
 ],
 "variables": [
    {
       "name": "newVariableName1",
       "value": "newVariableValue1"
    },
    {
       "name": "newVariableName2",
       "value": "YYYY-MM-DD"
    }
 ]
}

Parameters
contactListId `'required'`	ID of the contact list to which the contact belongs. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
contact `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in corresponding contactList
templateId `'required'`	The template you want to send. The template should be already created in your account on Templates page: `https://partner.smartsender.io/templates/`
tags ‘optional’	An array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or change frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
variables ‘optional’	You can add an associative array of custom variables which will be placed in your template which we host. Please, take in account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Content Custom Variables; `Third Priority`: Varible from the selected list.
	name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
	value `'required'`	Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly

Response:

{
   "result"   :true,
   "messageId":"5d91513fd132d5f462796870"
}

Return value
result	The value indicates that the triggered message was successfully sent out.
result	true	Message was successfully sent out
messageId	The message unique identification number in SmartSender system. With this ID number you can get all the statistics on each sent message.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the message
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument contactListId must be a non-empty string”
	“Argument contact must be a non-empty string”
	“Argument templateId must be a non-empty string”
	“Argument tags must be an array”
	“tag name must be a non-empty string”
	“Argument variables must be an array of arrays with \”name\” and \”value\” fields”
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“Payment required”
	“Contact list with id {contactListId} not found”
	“Template with id {templateId} not found”
	“Contact {contact} not found in list {contactListId}”
	“Contact {contact} is not active”
	“Contact {contact} is not subscribed to email”
	“Contact {contact} has not email address”
	“Unable to create html and text versions form template”
	“fail to publish message”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/mailer/trigger';

$body = json_encode([
  'contactListId' => 'YOUR_CONTACT_LIST_ID',
  'contact'       =>  'user@example.com',
  'templateId'    =>  'YOUR_TEMPLATE_ID',
  'tags'          =>  [
     'triggerTag'
  ],
     'variables'  => [
     [
       'name'     => 'newVariableName1',
       'value'    => 'newVariableValue1'
     ],
     [
       'name'     => 'newVariableName2',
       'value'    => 'YYYY-MM-DD'
     ]
  ],
 ]);


/**
* Documentation Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "Access-Token: $accessToken",
 'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);
exit;

/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "Access-Token: $accessToken",
   'Content-Type: application/json',
   'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

Get Message Statistics#

To get all the message statistics by message id you need to send POST Request to the following URL

https://api.smartsender.io/v3/mailer/info

Request body:

{
 "ids": [
     "YOUR_MESSAGE_ID_1",
     "YOUR_MESSAGE_ID_2",
     "YOUR_MESSAGE_ID_3"
 ]
}

Parameters
ids `'required'`	List of message ID numbers. You can include `only 100 IDs` in one request.

Response:

{
   "emails":[
   {
    "id":"5d914c3dd132d5f45a4e3670",
    "status":"delivered",
    "from":{
    "email":"user@senderdomain.com",
    "name":"Sender Name"
   },
   "subject":"Hello subject",
   "to":{
   "name":"Contact Name",
   "email":"user@recepientdomain.com"
  },
  "headers":{
  "X-Additional-Header":"additional-header-value",
 },
 "text":"",
 "html":"",
 "events":[
 {
  "event":"read",
  "datetime":"2019-09-30 00:42:54"
 }
 ]
}
],
"result":true
}

Messages returns a list of requested messages.
result	The sending status of the recipient:
	true	The message is accepted and queued
	false	The message is rejected
emails	id	The message unique identification number in SmartSender system
	status
		delivered	The send status is assigned as soon as SmartSender sent the message and it was accepted by the recipient ISP server.
		hard	The time and hard-bounce code received from the ISP
		soft	The time and soft-bounce code received from the ISP
	from	An array of sender information..
		email	The sender email address name
		name	Optional from name to be used
	subject	The message subject
	to	An array of recipient information.
		name		The email address of the recipient
		email		The optional display name of the recipient
	headers	Optional extra headers to add to the message (most headers are allowed)
	events	Email statistics includes detailed information on each message in the account. List of available events:
		sent	The send status is assigned as soon as SmartSender received a message.
		delivered	The send status is assigned as soon as SmartSender sent the message and it was accepted by the recipient ISP server.
		read	The read status is assigned every time this message has been opened by the user. The message includes information on each read.
		click	The click status is assigned every time tracked URLs in this message have been clicked by the user. The message includes information on each click.
		hard	The time and hard-bounce code received from the ISP
		soft	The time and soft-bounce code received from the ISP

Example Error Response JSON

{
  "result":false,
  "errors":[
  "Error description"
  ]
 }

Errors. The reason for the rejection.
result	The sending status of the message
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument ids must be an array of strings”
	“Argument ids can not be empty”
	“each id must be a non-empty string”
	“ids count must be less or equal 100”
	“Invalid authorization token!”
	“Intern al server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
   $url         = 'https://api.smartsender.io/v3/mailer/info';

   $body   = json_encode([
   'ids' => [
   '5c6afe9919b60506ac4262db',
   '5c6afc3f19b60506ac4262d6',
   '5c6afc3f19b60506ac4262d7',
   '5c6afc3f19b60506ac4262d8',
   ],
   ]);

   /**
   * Documentation Example
   */
   $ch = curl_init($url);
   curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
   curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
   curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
   curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
   //curl_setopt($ch, CURLOPT_HEADER, true);
   curl_setopt($ch, CURLOPT_INFILESIZE, null);
   curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "Access-Token: $accessToken",
   'Content-Type: application/json',
   ]);

   $result = curl_exec($ch);
   if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
  } else {
  echo strval($result) . PHP_EOL;
 }
 curl_close($ch);

 exit;

 /**
 * Request Example
 */
 $ch = curl_init($url);
 curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
 curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
 //curl_setopt($ch, CURLOPT_HEADER, true);
 curl_setopt($ch, CURLOPT_INFILESIZE, null);
 curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
 curl_setopt($ch, CURLOPT_HTTPHEADER, [
 "Access-Token: $accessToken",
 'Content-Type: application/json',
 'Content-Length: ' . strlen($body),
 ]);

 $result = curl_exec($ch);
 if ($result === false) {
 echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
echo strval($result) . PHP_EOL;
}
curl_close($ch);

Send SMS#

To send transactional or triggered SMS you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/sms/...

INFO The request body should contain a JSON with the SMS details.

Below you can find detailed information on usage of different methods to send SMS with SmartSender.

Send A New SMS#

To send a SMS you need to send POST Request to the following URL

https://api.smartsender.io/v3/sms/send

Request body:

{
   "domain":"senderDomain.com",
   "phoneNumber":"+1555555555",
   "fromName":"SenderName",
   "text":"Hi, API Sms!",
   "tags":[
      "smsApiSend"
   ]
}

Parameters
domain ‘optional’	Verified domain name from your SmartSender account. This data is used to send you webhooks and generate reports.
phoneNumber `'required'`	Addressee phone number. `IMPORTANT:` should be `valid E.164 phone number`.
fromName ‘optional’	Sender’s from name linked to sending phone number addressee will see in their phones. If not defined – default from name linked to sending phone number will be used.
text `'required'`	SMS text you want to send.
tags ‘optional’	You can add custom tags to your messages to ease stats collections (mark templates, campaigns, etc). A single tag – must not start with an underscore

Response:

{
   "result":true,
   "sms_id":"5d91513fd132d5f462796870"
}

Return value
sms_id	The sms unique identification number in SmartSender system.
result	The value indicates that the SMS was successfully send.
	true	SMS was successfully send

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the SMS message.
	true	The SMS message is accepted and queued
	false	The SMS message is rejected
Error description	“Argument domain must be a non-empty string”
	“Argument phoneNumber must be a non-empty string”
	“{phoneNumber} is not a valid E.164 phone number”
	“Argument text must be a non-empty string”
	“Argument fromName must be a non-empty string”
	“Argument fromName must contain 11 and less A-Z, a-z, 0-9 symbols and spaces or be a valid phoneNumber”
	“Argument tags must be an array”
	“tag name must be a non-empty string”
	“SMS service is not activated for account {accountName}”
	“Insufficient balance. You need at least {cost} to send this message”
	“Phone number {phoneNumber} is blacklisted”
	“Domain {domain} not found in your account”
	“Publishing error”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/sms/send';

$body = json_encode([
   'domain'      => 'senderDomain.com',
   'phoneNumber' => '+1555555555',
   'fromName'    => 'senderName',
   'text'        => 'Hi, API SMS!',
   'tags'        => [
      'smsApiSend',
   ],
]);

/**
* Documentation Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

Send Triggered SMS#

To send a triggered SMS you need to send POST Request to the following URL

https://api.smartsender.io/v3/sms/trigger

Request body:

{
   "contactListId":"YOUR_CONTACT_LIST_ID",
   "contact":"+155555555",
   "fromName":"SenderName",
   "text":"Hi, {{name}}! Your phone: {{phoneNumber}} Var1: {{newVariableName}}",
   "tags":[
      "smsApiTrigger"
   ],
   "variables":[
      {
         "name":"newVariableName",
         "value":"newVariableValue"
      }
   ]
}

Parameters
contactListId `'required'`	ID of the contact list to which the contact belongs. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
contact `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in corresponding contactList.
fromName ‘optional’	Sender’s from name linked to sending phone number recipient will see in their phones. If not defined – default from name linked to contactList will be used
text `'required'`	SMS text you want to send.
tags ‘optional’	You can add custom tags to your messages to ease stats collections (mark templates, campaigns, etc). A single tag – must not start with an underscore
variables ‘optional’	You can add an associative array of custom variables which will be placed in your template which we host. Please, take in account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Content Custom Variables; `Third Priority`: Varible from the selected list.
	name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
	value `'required'`	Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly

Response:

{
 "result":true,
 "sms_id":"5d91513fd132d5f462796870"
}

Return value
sms_id	The sms unique identification number in SmartSender system.
result	The value indicates that the SMS was successfully send.
	true	SMS was successfully send

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the SMS message.
	true	The SMS message is accepted and queued
	false	The SMS message is rejected
Error description	“Argument contactListId must be a non-empty string”
	“Argument contact must be a non-empty string”
	“Argument contact must be a valid email address or E.164 phone number. {contact} given”
	“Argument text must be a non-empty string”
	“Argument froName must be a non-empty string”
	“Argument fromName must contain 11 and less A-Z, a-z, 0-9 symbols and spaces or be a valid ph oneNumber”
	“Argument tags must be an array”
	“Tag name must be a non-empty string”
	“Argument variables must be an array of arrays with \”name\” and \”value\” fields”
	“Name of variable must be a string”
	“Name of variable can not be empty”
	“Variable \”{name}\” is reserved and can not be added as custom variable”
	“Invalid name of variable {name}”
	“SMS service is not activated for account {accountName}”
	“Contact list {contactListId} not found”
	“Contact {contact} is not active“
	“Contact {contact} not found in list {contactListId}”
	“Contact {contact} is not subscribed to SMS”
	“Contact {contact} has not phone number”
	“Contact phone number {phoneNumber} is blacklisted”
	“Insufficient balance. You need at least {cost} to send this message”
	“Publishing error”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“User {id} not enabled”
	“no data found for key {userId}”
	“Access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/sms/trigger';

$body = json_encode([
    'contactListId' => 'YOUR_CONTACT_LIST_ID',
    'contact'       => '+155555555',
    //    'contact' => 'user@example.com',
    //    'contact' => 'userId',
    'fromName'      => 'senderName',
    'text'          => 'Hi, {{name}}! Your phone: {{phoneNumber}} Var1: {{newVariableName}}',
    'tags'          => [
        'smsApiTrigger',
    ],
    'variables'     => [
        [
            'name'  => 'newVariableName',
            'value' => 'newVariableValue'
        ],
    ],
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Get SMS Delivery Status#

To get SMS delivery status by sms_id you need to send POST Request to the following URL:

https://api.smartsender.io/v3/sms/info

Request body:

{
   "ids":[
      "5d91537bd132dsf45916520a",
      "5bc0a73d19b6051f963023c2",
      "5bc0a73d19b6051f963023c3"
   ]
}

Parameters
ids `'required'`	List of message ID numbers. You can include `only 100 IDs` in one request.

Response:

{
 "result":true,
 "data":{
  "5d91537bd132fdf45916520a":{
   "id":"5d91537bd132fdf45916520a",
   "status":"delivered",
   "createdAt":"2019-09-30 00:59:39",
   "text":"Hi, user! Your phone: +15555555 Var1: apiVar1Val",
   "phoneNumber":"+15555555",
   "fromName":"Sender name"
  },
  "5 bc0a73d19b6051f963023c2":null,
  "5bc0a73d19b6051f963023c3":null
 },
 "errors":[
  "SMS 5bc0a73d19b6051f963023c2 not found",
  "SMS 5bc0a73d19b6051f963023c3 not found"
 ]
}

Return value You will get a list of successfully fetched ids and list of errors for failed ones.
result	The value indicates that the request was successful.
	true	Statistics was successfully fetched
data	An array of fetched information.
	id	sms_id of the message
	status	new	Messages start here, this is temporary status before processing further.
		failed	Message delivery was failed. Possible reasons: Mobile network rejected the message or the message has exceeded it’s validity period without getting a delivery confirmation.
		queued	The message is held in our internal queue and awaits delivery to the mobile network.
		sent	The message has been sent to mobile network, and is on it’s way to it’s final destination.
		delivered	The end user’s mobile decide has confirmed the delivery
		undelivered	Message is permanently undeliverable. Most likely an invalid MSISDN
	createdAt	Message creation UTC DateTime.
	text	The content of the SMS.
	phoneNumber	recipient’s phone number
	fromName	Sender name used in the SMS
errors	An array of failed id fetches and error messages with description of why request was rejected.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the SMS message.
	true	The SMS message is accepted and queued
	false	The SMS message is rejected
Error description	“Argument ids must be an array of strings”
	“Argument ids can not be empty”
	“each id must be a non-empty string”
	“ids count must be less or equal 100”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/sms/info';
$body = json_encode([
    'ids' => [
        '5bc0a73d19b6051f963023c1',
        '5bc0a73d19b6051f963023c2',
        '5bc0a73d19b6051f963023c3',
    ],
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Send Web Push Notifications#

To send transactional or triggered Web Push Notifications, you need to send a POST Request with your Access Token in headers to specific URL based on the following format:

https://api.smartsender.io/v3/web-push/...

The request body should contain a JSON with the Notification details.

INFO The request body should contain a JSON with the Web Push details.
Below you can find detailed information on the usage of different methods to send Web Pushes with SmartSender.

Send A New Web Push#

To send a Web Push you need to send POST Request to the following URL

https://api.smartsender.io/v3/web-push/send

Request body:

{
   "contactListId": "YOUR_CONTACT_LIST_ID",
   "domain":        "senderDomain.com",
   "contact":       "user@example.com",
   "title":         "PUSH_TITLE",
   "text":          "PUSH_CONTENT_TEXT",
   "link":          "FINAL_DESTINATION_URL",
   "image":         "ICON_IMAGE_URL",
   "tags": [
      "pushNotificationTag"
   ],
   "device":        "desktop",
   "ttl":           360
}

Parameters
contactListId `'required'`	ID of the contact list which the contact belongs to. The list should be already created in your account on the Lists page: `https://partner.smartsender.io/email-list/`
domain `'required'`	Verified domain name from your SmartSender account. This data is used to send you webhooks and generate reports.
contact `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the corresponding contactList.
title `'required'`	Text title to be sent via web push.
text `'required'`	Web Push content text you want to send.
link `'optional'`	Link to the page where subscribers will get when they click on the link
image `'optional'`	Shows subscribers who’ve sent the the web push notification. `WARNING:`if you don’t use an icon, the user will see a standard browser logo.
tags `'optional'`	An array of string to tag the message with. Stats are accumulated using tags, though we only store the first 100 we see, so this should not be unique or changed frequently. Tags should be 50 characters or less. Any tags starting with an underscore are reserved for internal use and will cause errors.
device `'optional'`	Add kinds of browsers to the parameter. Available options: `Important:`By default, we send to both browsers
	desktop	Notifications will only be shown on the desktop version of the browser.
	mobile	Notifications will only be shown on the mobile version of the browser.
ttl `'optional'`	Time to live must be specified in seconds. Between 30 minutes to 72 hour.,

Response:

{
   "result":true,
   "notifications_ids":"5d914c3dd132d5f45a4e3670"
}

Return Value the sending results for a single recipient
notifications_ids	The notification unique identification number in SmartSender system. With this ID number you can get all the statistics on each sent notification.
result	The sending status of the recipient:
	true	The notification is accepted and queued
	false	The notification is rejected

Example Error Response JSON:

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the message.
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument contactListId must be a non-empty string”
	“Argument domain must be a non-empty string”
	“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
	“Argument title must be a non-empty string”
	“Argument text must be a non-empty string”
	“Argument link must be a non-empty string of valid URL”
	“Argument image must be a non-empty string of valid image URL with aspect 1:1 and recommended size between 84×84 and 128×128”
	“Width of image must be between 84 and 128 pixels”
	“Height of image must be between 84 and 128 pixels”
	“Aspect ratio must be 1:1”
	“Use https instead of http”
	“Argument device must be a non-empty string”
	“Argument device must be mobile or desktop”
	“Argument tags must be an array”
	“Tag name must be a non-empty string”
	“Argument ttl must be a numeric”
	“Argument ttl must be between 30 minutes and 72 hours reproduced by seconds value”
	“Argument device must be a non-empty string”
	“Argument device must be mobile or desktop”
	“Your notification data is to long. Maximum count of characters is 4078”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”,
	“no data found for key {userId}”,
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example:

$accessToken = "YOUR_API_KEY=";
$url = 'https://api.smartsender.io/v3/web-push/send';
$body = json_encode([
    'contactListId'=> 'YOUR_CONTACT_LIST_ID',
    'domain'=> 'senderDomain.com',
    'contact'=> 'user@example.com',
    'title'=> 'PUSH_TITLE',
    'text'=> 'PUSH_CONTENT_TEXT',
    'link'=> 'FINAL_DESTINATION_URL',
    'image'=> 'ICON_IMAGE_URL',
    'tags'=> [
        'pushNotificationTag'
    ],
    'device'=> 'desktop',
    'ttl'=> 3600
]);
echo json_encode(json_decode($body, true), 128) . PHP_EOL;
/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Send Triggered Web Push#

To send a triggered Web Push, you need to send POST Request to the following URL.

https://api.smartsender.io/v3/web-push/trigger

Request body:

{
  "contactListId": "YOUR_CONTACT_LIST_ID",
  "contact": "user@example.com",
  "templateId": "YOUR_PUSH_TEMPLATE_ID", 
  "tags": [
     "triggerTag"
  ], 
  "variables": [ 
     { 
        "name": "variableName", 
        "value": "variableValue"
     } 
  ],
  "device": "desktop or mobile", 
  "ttl": 360 
}

Parameters
contactListId `'required'`	ID of the contact list which the contact belongs to. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
contact `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the corresponding contactList.
templateId `'required'`	The Push template you want to send. The template should be already created in your account on the Templates page: `https://partner.smartsender.io/web-push-template/`
variables `'optional'`	You can add an associative array of custom variables that will be placed in your template which we host. Please take into account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Content Custom Variables; `Third Priority`: Variable from the selected list.
	name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only Latin `lowerCamelCase` format. No numbers or other symbols are allowed.
	value `'required'`	Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly
tags `'optional'`	You can add custom tags to your messages to ease stats collections (mark templates, campaigns, etc). A single tag – must not start with an underscore.
device `'required'`	Add kinds of browsers to the parameter. Available options: `Important:`By default, we send to both browsers.
	desktop `'optional'`	Notifications will only be shown on the desktop version of the browser
	mobile `'optional'`	Notifications will only be shown on the mobile version of the browser
ttl `'optional'`	Time to live must be specified in seconds. Between 30 minutes to 72 hours.

Response:

{
"result":true,
"notifications":["5e1c888bd132d5e7d00f17f8"]
}

Return value
result	The value indicates that the triggered message was successfully sent out.
	true	Message was successfully sent out.
notifications	The message unique identification number in the SmartSender system. With this ID number you can get all the statistics on each sent message.

Example Error Response JSON:

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the message.
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument contactListId must be a non-empty string”
	“Argument contact must be a non-empty string”
	“Argument templateId must be a non-empty string”
	“Argument tags must be an array”
	“tag name must be a non-empty string”
	“Argument variables must be an array of arrays with \”name\” and \”value\” fields”
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“Argument device must be a non-empty string”
	“Argument device must be mobile or desktop”
	“Argument ttl must be a numeric”
	“Argument ttl must be between 30 minutes and 72 hours reproduced by seconds value”
	“Payment required”
	“Contact list with id {contactListId} not found”
	“Template with id {templateId} not found”
	“Contact {contact} not found in list {contactListId}”
	“Conta ct {contact} is not active”
	“Contact {contact} is not subscribed to email”
	“Unable to create content from template”
	“fail to publish message”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access tok en {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example:

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/web-push/trigger';
$body = json_encode([
    'contactListId'=> 'YOUR_CONTACT_LIST_ID',
    'domain'=> 'senderDomain.com',
    'contact'=> 'user@example.com',
    'templateId'=> 'YOUR_TEMPLATE_ID',
    'tags'=> [
'triggerTag'
],
'variables'=> [
   [
      'name'=> 'variableName',
      'value'=>'variableValue' 
   ],
],
  'device'=> 'desktop',
  'ttl' => 3600
]);
echo json_encode(json_decode($body, true), 128) . PHP_EOL;
/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Get Web Push Status#

To get a Web Push status by Web Push_id, you need to send POST Request to the following URL:

https://api.smartsender.io/v3/web-push/info

Request body:

{
  "ids": [
     "YOUR_PUSH_ID_1",
     "YOUR_PUSH_ID_2",
     "YOUR_PUSH_ID_3"
  ]
}

Parameters
ids `'required'`	List of message ID numbers. You can include only 100 IDs in one request.

Response:

{
  "notifications":[
     {
         "id":"YOUR_PUSH_ID_1",
         "status":"delivered",
         "to":{
             "name":"userName",
             "email":"user@example.com"
         },
         "title":"PUSH_TITLE",
         "text":"PUSH_CONTENT_TEXT",
         "link":"https:\/\/FINAL_DESTINATION_URL\/",
         "image":"http:\/\/ICON_IMAGE_URL\/",
         "events":[
            {
               "event":"viewed",
               "datetime":"YYYY-MM-DD h:i:s"
            },
            {
               "event":"delivered",
               "datetime":"YYYY-MM-DD h:i:s"
            },
            {
               "event":"dismissed",
               "datetime":"YYYY-MM-DD h:i:s"
            }
          ]
      }
   ],
   "result":true
}

Messages returns a list of requested messages.
result	The sending status of the recipient:
	true	The message is accepted and queued
	false	The message is rejected
notifications	id	The message unique identification number in SmartSender system
	status	The message unique identification number in SmartSender system
		delivered	The notification was delivered
		undelivered	The notification wasn’t delivered, invalid token
		expired	The notification wasn’t shown due to TTL (Time to live)
	to	An array of recipient information.
		name	The optional display name of the recipient
		email	The email address of the recipient
	title	The Push notification title
	text	Web Push content text you want to send.
	link	Link to the page where subscribers will get when they click on the push
	image	Icon which subscribers will see when they get the notification
	events	Push statistics includes detailed information on each push notification in the account. List of available events:
		viewed	The status is assigned as soon as the user viewed the notification.
		delivered	The notification was delivered
		dismissed	The status is assigned every time this message has been closed by the user.
		click	The status is assigned every time URLs in this notification have been clicked by the user
		expired	The notification wasn’t shown due to TTL (Time to live)
		undelivered	The notification wasn’t delivered, invalid token

Example Error Response JSON:

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The sending status of the message.
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument ids must be an array of strings”
	“Argument ids can not be empty”
	“Each id must be a non-empty string”
	“Ids count must be less or equal 100”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example:

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/web-push/info';
$body = json_encode([
    'ids' => [
       'YOUR_PUSH_ID_1',
       'YOUR_PUSH_ID_2',
       'YOUR_PUSH_ID_3'
    ],
]);
echo json_encode(json_decode($body, true), 128) . PHP_EOL;
/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Manage Variables#

To add | update | remove | get your account variables you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/global-variables/...

INFO The request body should contain a JSON with the variable details.

Below you can find detailed information on usage of different methods to manage your account variables.

Create Account Variable#

To add an account variable you need to send POST Request to the following URL

https://api.smartsender.io/v3/global-variables/create

Request body:

{
    "name": "globalVarName",
    "value": "globalVarValue"
}

Parameters
name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
value `'required'`	Variable value in `'ENUM_STRING'` format.

Response:

{
 "result":true
}

Return value
result	The value indicates that the variable was successfully added to your account.
	true	Variable was successfully added

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“name of variable must be a string”
	“name of variable can not be em pty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/global-variables/create';
$body = json_encode([
    'name' => 'globalVarName',
    'value' => 'globalVarValue',
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Update Account Variable#

To update a contact data in Contact List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/global-variables/update

Request body:

{
    "name": "globalVarName",
    "value": "globalVarNewValue"
}

Parameters
name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
value `'required'`	Variable value in `'ENUM_STRING'` format.

Response:

{
    "result": true
}

Return value
result	The value indicates that the variable was successfully updated in your account.
	true	Variable was successfully updated

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“Invalid authorization token!”
	“Internal se rver error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/global-variables/update';
$body = json_encode([
    'name' => 'globalVarName',
    'value' => 'globalVarNewValue',
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Get Account Variables#

To add an account variable you need to send POST Request to the following URL

https://api.smartsender.io/v3/global-variables/find

Request body:

{
    "name": "globalVarName"  //Send empty array to get all account global variables.
}

name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.

Response:

{
   "name":"globalVarName",
   "value":"globalVarValue",
   "createdAt":"YYYY-MM-DD h:i:s"
}

Return value
Response body	The value indicates that the variable information was successfully fetched from your account
	name	Variable name
	value	Variable Value
	createdAt	Indicates time when variable was added

Example Error Response JSON

{    
   "result":false,    
   "errors":[    
      "Error description text"    
   ]    
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
“Argument name must be a non-empty string”
	“no matches found for global variable {globalVariable}”
	“no global variables found”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/global-variables/find';

$body = json_encode([
    'name' => 'globalVariable',  //Send empty array to get all account global variables.
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

//exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Remove Account Variable#

To delete an account variable you need to send POST Request to the following URL

https://api.smartsender.io/v3/global-variables/remove

Request body:

{
    "name": "globalVarName"
}

Parameters
name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.

Response:

{
    "result": true
}

Return value
result	The value indicates that the variable was successfully deleted from your account.
	true	Variable was successfully deleted

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/global-variables/remove';

$body = json_encode([
    'name' => 'globalVarName',
]);


/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Manage Contact List#

To update a contact data from the contact list you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contacts/...

INFO The request body should contain a JSON with the required information.

Below you can see the table with required parameters.

Add A New Contact#

To add a contact to the Contact List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contacts/add

Request body:

{
    "contactListId": "YOUR_CONTACT_LIST_ID",
    "webHookUri": "YOUR_WEBHOOK_URL",
    "contacts": [
        {
            "name": "Contact Name",
            "email": "user@example.com",
            "phoneNumber": "+15555555",
            "userId": "myUserId",
            "active": true,
            "emailSubscribe": true,
            "smsSubscribe": true,
            "sourceId": "5efc8503efeef96ca3151931",
            "cac": {
                    "value": 2.05,
                    "currency": "EUR"
                   }
            "variables": [
                {
                    "name": "newVariableName",
                    "value": "newVariableValue"
                }
            ]
        }
    ]
}

Parameters
contactListId `'required'`	ID of the contact list where the contact to be updated belongs. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
webHookUri ‘optional’	SmartSender will send a `POST` request to your `webHookUri` with the status of the request as soon as it is processed.
contact `'required'`	An array of contact information. `WARNING`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
	name `'optional'`	The optional display name to use for the recipient
	email `'optional'`	Contact’s email address.
	phoneNumber `'optional'`	`IMPORTANT:` should be `valid E.164 phone number`.
	userId `'optional'`	Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
	active `'optional'`	You can set if the contact is enable contact list or not. The default value is false (disable).
		true ‘optional’	Contact enabled. Contact can receive communication from enabled channels.
		false `'default'`	Contact disabled. No communications will be send to this contact.
	emailSubscribe ‘optional’	You can set if the contact is subscribed to receiving emails or not. The default value is false (unsubscribed).
		true ‘optional’	Subscribe contact to emails
		false `'default'`	Unsubscribe contact from emails
	smsSubscribe ‘optional’	You can set if the contact is subscribed to receiving SMS or not. The default value is false (unsubscribed).
		true ‘optional’	Subscribe contact to SMS
		false `'default'`	Unsubscribe contact from SMS
	variables ‘optional’	An array of contact variables and their values.
		name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
		value `'required'`	Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly
	sourceId ‘optional’	Contact’s unique source ID from SmartSender platform
	cac ‘optional’	value `'required'`	CAC value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly
		currency `'required'`	(EUR, USD) `WARNING:` Please use only latin uppercase format. No numbers or other symbols allowed.

Response:

{
  "result":true,
  "requestId":"5d915c22d132d5f45a4e38b8",
  "errors":[]
}

Return value
result	The value indicates that the contact was successfully added to your contact list.
	true	Contact was successfully added
requestId	Unique request ID to be used to match the specific “Add contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.

Example Error Response JSON

{
   "result":false,
   "requestId":"REQUEST_ID",
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and queued. The result will be sent via webhook to provided link.
	false	The request is rejected
requestId	Unique request ID to be used to match the specific “Add contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
Error description	“Argument contactListId must be a non-empty string”
	“Argument webHookUri must be a valid URI”
	“add at least one valid contact to contacts field”
	“Argument name must be a string”
	“invalid RFC2822 email {email} at email field”
	“Argument email must be a string”
	“Argument phoneNumber must be a string”
	“{phoneNumber} is not a valid E.164 p hone number”
	“Argument userId must be a string”
	“Argument active can be true or false”
	“Argument emailSubscribe can be true or false”
	“Argument smsSubscribe can be true or false”
	“Argument variables must be an array of arrays with \”name\” and \”value\” fields”
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“List with id {contactListId} not found!”,
	“email, phoneNumber or externalId\/userId must be filled at contact position {i}”
	“Variable {name} type is date, but v alue is not valid date. Value {value}”
	“Variable {name} not found in list. Try to add it first”
	“Request saving error. Please, contact us or try again later”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for acces s token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key \/$accessToken”
	“Argument {argument} required”
	“Argument sourceId must be a string”
	“sourceId {sourceId} not found in your account at contact position {i}”
	“Argument CAC must be an array with value and currency fields”
	“CAC value must be a positive float”
	“CAC currency {currency} not allowed. USD, EUR are”

Example Request status webhook

If you have provided webHookUri in your request, SmartSender will send a POST request to it with the status of the request as soon as it is processed.

{
    "event": "contact_management_request",
    "datetime": Unix_Timestamp,
    "requestId": "REQUEST_ID",
    "results": {
        "success": [
            {
                "id": "SMARTSENDER_CONTACT_ID",
                "email": "user@example.com",
                "phone": "+15555555",
                "userId": "myUserId"
            }
        ],
        "errors": [
            {
                "contact": {
                    "id": "",
                    "email": "user+2@example.com",
                    "phone": "+15555556",
                    "userId": "myUserId+2"
                },
                "error": "Error code",
                "humanError": "Error description"
            }
        ]
    }
}

event	Event type: `'contact_management_request'`
datetime	Request time in `Unix_Timestamp` format
requestId	Unique request ID to be used to match the specific “Add contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
results	success	“Sucess” status for all successfully processed requests
		id	Contact ID in SmartSender platform. For informational purposes only.
		email	Contact’s email address.
		phone	Contact’s phone number.
		userId	Contact’s unique user ID from your platform
	errors	“Errors” for all failed requests with fail reason description.
		contact	Array of contact information
			id	Contact ID in SmartSender platform. For informational purposes only.
			email	Contact’s email address.
			phone	Contact’s phone number.
			userId	Contact’s unique user ID from your platform
		errors	“ERR_EMPTY_IDENTIFIERS”
			“ERR_CONTACT_EXISTS”
			“ERR_CONTACT_DUPLICATION_ATTEMPT”
			“ERR_SYSTEM_ERROR”
			“ERR_CONTACT_NOT_EXISTS”
			“ERR_INVALID_VARIABLE_NAME”
		humanError	“No identifiers to work with contact”
			“Trying to set all contact\’s identifiers empty”
			“Contact already exists”
			“duplication attempt”
			“system error”
			“contact not exists”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/contacts/add';

$body = json_encode([
    'contactListId' => 'YOUR_CONTACT_LIST_ID',
    'webHookUri' => 'YOUR_WEBHOOK_URL',
    'contacts'      => [
        [
            "name"           => "Contact Name",
            "email"          => "user@example.com",
            "phoneNumber"    => "+15555555",
            "userId"         => "myUserId",
            "active"         => true,
            "emailSubscribe" => true,
            "smsSubscribe"   => true,
            "sourceId"       => 5efc8503efeef96ca3151931,
            "cac"            => [
                  "value"    => "2.05", 
                  "currency" => "EUR",
                ],
            "variables"      => [
                [
                    "name"   => "newVariableName",
                    "value"  => "newVariableValue",
                ],
            ],
        ],
    ],
]);
echo json_encode(json_decode($body, true), 128) . PHP_EOL;
/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Update Contact Data#

To update a contact data in Contact List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contacts/update

Request body:

{
    "contactListId": "YOUR_CONTACT_LIST_ID",
    "webHookUri": "YOUR_WEBHOOK_URL",
    "upsert": false,
    "contacts": [
        {
            "contact": "user@example.com",
            "name": "Contact Name",
            "email": "newUser@example.com",
            "phoneNumber": "+15555555",
            "userId": "myUserId",
            "active": true,
            "emailSubscribe": true,
            "smsSubscribe": true,
            "desktopWebPushSubscribe": true,
            "mobileWebPushSubscribe": true,
            "sourceId": "5efc8503efeef96ca3151931",
            "cac": {
                "value": 2.05,
                "currency": "USD"
                }
        }
    			]
            "variables": [
                {
                    "name": "newVariableName",
                    "value": "newVariableValue"
                }
            ]
        }
    ]
}

Parameters
contactListId `'required'`	ID of the contact list where the contact to be updated belongs. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
webHookUri ‘optional’	SmartSender will send a `POST` request to your `webHookUri` with the status of the request as soon as it is processed.
upsert `'optional'`	You can set if the contact should be added to the list if it does not exist at the time of the request.
	true `'optional'`	Create new contact if it does not exist
	false `'default'`	Do not create contact if it does not exist
contacts `'required'`	An array of information on contacts batch you want to update. `WARNING:`You can update only `100` contacts at once.
	parameters `'required'`	An array of contact information. `WARNING`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
		contact `'required'`	The unique user identificator (`userId` \| `email` \| `phoneNumber`) of the contact you want to update
		name `'optional'`	The optional display name to use for the recipient
		email `'optional'`	Contact’s email address.
		phoneNumber `'optional'`	`IMPORTANT:` should be `valid E.164 phone number`.
		userId `'optional'`	Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
		active `'optional'`	You can set if the contact is enable contact list or not. The default value is false (disable).
			true ‘optional’	Contact enabled. Contact can receive communication from enabled channels.
			false `'default'`	Contact disabled. No communications will be send to this contact.
		emailSubscribe ‘optional’	You can set if the contact is subscribed to receiving emails or not. The default value is false (unsubscribed).
			true ‘optional’	Subscribe contact to emails
			false `'default'`	Unsubscribe contact from emails
		smsSubscribe ‘optional’	You can set if the contact is subscribed to receiving SMS or not. The default value is false (unsubscribed).
			true ‘optional’	Subscribe contact to SMS
			false `'default'`	Unsubscribe contact from SMS
		desktopWebPushSubscribe ‘optional’	You can set if the contact is subscribed to receiving emails or not. The default value is false (unsubscribed).
			true ‘optional’	Subscribe contact to desktop webpush notifications
			false `'default'`	Unsubscribe contact from desktop webpush notifications
		mobileWebPushSubscribe ‘optional’	You can set if the contact is subscribed to receiving emails or not. The default value is false (unsubscribed).
			true ‘optional’	Subscribe contact to mobile webpush notifications
			false `'default'`	Unsubscribe contact from mobile webpush notifications
		variables ‘optional’	An array of contact variables and their values.
			name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
			value `'required'`	Variable value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly
		sourceId ‘optional’	Contact’s unique source ID from SmartSender platform
		cac ‘optional’	value `'required'`	CAC value in `'ENUM_STRING'` or `'ENUM_DATE'` format correspondingly
			currency `'required'`	(EUR, USD) `WARNING:` Please use only latin uppercase format. No numbers or other symbols allowed.

Response:

{
  "result":true,
  "requestId":"5d915c22d132d5f45a4e38b8",
  "errors":[]
}

Return value
result	The value indicates that the contact was successfully added/updated to your contact list.
	true	Contact was successfully added/updated
requestId	Unique request ID to be used to match the specific “Update contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.

Example Error Response JSON

{
   "result":false,
   "requestId":"REQUEST_ID",
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and queued. The result will be sent via webhook to provided link.
	false	The request is rejected
requestId	Unique request ID to be used to match the specific “Update contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
Error description	“Argument contactListId must be a non-empty string”
	“Argument upsert must be a true or false”
	“Argument webHookUri must be a valid URI”
	“add at least one valid contact to contacts field”
	“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
	“Argument name must be a string”
	“invalid RFC2822 email {email} at email field”
	“Argument email must be a string”
	“Argument phoneNumber must be a string”
	“{phoneNumber} is not a valid E.164 phone number”
	“Argument userId must be a string”
	“Argument active can be true or false”
	“Argument emailSubscribe can be true or false”
	“Argument smsSubscribe can be true or false”
	“Argument variables must be an array of arrays with \”name\” and \”value\ “fields”
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“List with id {contactListId} not found!”
	“email, phoneNumber or externalId\/userId must be filled at contact position {i}”
	“Variable {name} type is date, but value is not valid date. Value {value}”
	“Variable {name} not found in list. Try to add it first”
	“Request saving error. Please, contact us or try again later”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check fail ed for key\/secret $key\/$accessToken”
	“Argument {argument} required”
	“Argument sourceId must be a string”
	“sourceId {sourceId} not found in your account at contact position {i}”
	“Argument CAC must be an array with value and currency fields”
	“CAC value must be a positive float”
	“CAC currency {currency} not allowed. USD, EUR are”

Example Request status webhook

If you have provided webHookUri in your request, SmartSender will send a POST request to it with the status of the request as soon as it is processed.

{
    "event": "contact_management_request",
    "datetime": Unix_Timestamp,
    "requestId": "REQUEST_ID",
    "results": {
        "success": [
            {
                "id": "SMARTSENDER_CONTACT_ID",
                "email": "user@example.com",
                "phone": "+15555555",
                "userId": "myUserId"
            }
        ],
        "errors": [
            {
                "contact": {
                    "id": "",
                    "email": "user+2@example.com",
                    "phone": "+15555556",
                    "userId": "myUserId+2"
                },
                "error": "Error code"
            }
        ]
    }
}

event	Event type: `'contact_management_request'`
datetime	Request time in `Unix_Timestamp` format
requestId	Unique request ID to be used to match the specific “Add contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
results	success	“Sucess” status for all successfully processed requests
		id	Contact ID in SmartSender platform. For informational purposes only.
		email	Contact’s email address.
		phone	Contact’s phone number.
		userId	Contact’s unique user ID from your platform
	errors	“Errors” for all failed requests with fail reason description.
		contact	Array of contact information
			id	Contact ID in SmartSender platform. For informational purposes only.
			email	Contact’s email address.
			phone	Contact’s phone number.
			userId	Contact’s unique user ID from your platform
		errors	“ERR_EMPTY_IDENTIFIERS”
			“ERR_CONTACT_EXISTS”
			“ERR_CONTACT_DUPLICATION_ATTEMPT”
			“ERR_SYSTEM_ERROR”
			“ERR_CONTACT_NOT_EXISTS”
			“ERR_INVALID_VARIABLE_NAME”
		humanError	“No identifiers to work with contact”
			“Trying to set all contact\’s identifiers empty”
			“Contact already exists”
			“duplication attempt”
			“system error”
			“contact not exists”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/contacts/update';

$body = json_encode([
    'contactListId' => 'YOUR_CONTACT_LIST_ID',
    'webHookUri'    => 'YOUR_WEBHOOK_URL',
    'upsert'        => false,
    'contacts'      => [
        [
            "contact"          => "+15555555",
            "name"             => "Name",
            "email"            => "example@domain.dom",
            "phoneNumber"      => "+15444444",
            "userId"           => "myUserId",
            "active"           => true,
            "emailSubscribe"   => true,
            "smsSubscribe"     => true,
            "sourceId"         => 5efc8503efeef96ca3151931, 
            "cac"              => [ 
                    "value"    => "2.05", 
                    "currency" => "EUR", 
                     ],
            "variables"        => [
                [
                    "name"     => "testVar",
                    "value"    => "testVal",
                ],
            ],
        ],
    ],
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Remove Contact#

To remove a contact from Contact List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contacts/remove

Request body:

{
   "contactListId": "YOUR_CONTACT_LIST_ID",
   "webHookUri": "YOUR_WEBHOOK_URL",
   "emails": [
      "user-1@example.com",
      "user-2@example.com",
      "user-3@example.com"
   ],
   "phoneNumbers": [
      "+155555555",
      "+155555556"
   ],
   "userIds": [
      "myUserId-1",
      "myUserId-2"
   ]
}

Parameters
contactListId `'required'`	ID of the email list from which the contact should be removed. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
webHookUri `'optional'`	SmartSender will send a `POST` request to your `webHookUri` with the status of the request as soon as it is processed.
emails `'optional'`	An array of email addresses of contacts to be removed. You can remove more than one contact at once.
	email `'required'`	Contact’s email address. `WARNING:`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
phoneNumbers `'optional'`	An array of phone numbers of contacts to be removed. You can remove more than one contact at once.
	phone number `'required'`	Contact’s phone number. `IMPORTANT:` should be `valid E.164 phone number`. `WARNING`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
userIds `'optional'`	An array of userIds of contacts to be removed. You can remove more than one contact at once.
	userId `'required'`	Contact’s unique user ID from your platform to enable management of the contact in the list based on it. `WARNING:`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.

Response:

{
  "result":true,
  "requestId":"5d915c22d132d5f45a4e38b8"
}

Return value
result	The value indicates that the “Remove contact” request was successfully validated and accepted by SmartSender and queued for processing.
	true	Contact was successfully removed
requestId	Unique request ID to be used to match the specific “Remove contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.

Example Error Response JSON

{
   "result":false,
   "requestId":"5bc0a73d19b6051f963023c3",
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and queued. The result will be sent via webhook to provided link.
	false	The request is rejected
requestId	Unique request ID to be used to match the specific “Remove contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
Error description	“Maximum count of records per transaction is 100, current {n}”
	“Argument contactListId must be a non-empty string”
	“Argument webHookUri must be a valid URI”
	“Argument emails must be a list of emails”
	“Each email must be a string”
	“Argument phoneNumbers must be a list of phoneNumbers”
	“Each phoneNumber must be a string”
	“Argument u serIds must be a list of userIds”
	“Each userId must be a string”
	“List with id {contactListId} not found!”
	“add at least one contact to remove”
	“Request saving error. Please, contact us or try again later”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”,
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

Example Request status webhook

If you have provided webHookUri in your request, SmartSender will send a POST request to it with the status of the request as soon as it is processed.

{
    "event": "contact_management_request",
    "datetime": Unix_Timestamp,
    "requestId": "5df24169d132d50c882e9c39",
    "results": {
        "success": [
            {
                "id": "5df24169890edeec04138f81",
                "email": "user@example.com",
                "phone": "+15555555",
                "userId": "myUserId-1"
            }
        ],
        "errors": [
            {
                "contact": {
                    "id": "",
                    "email": "user+2@example.com",
                    "phone": "+15555556",
                    "userId": "myUserId+2"
                },
                "error": "Error code"
            }
        ]
    }
}

event	Event type: `'contact_management_request'`
datetime	Request time in `Unix_Timestamp` format
requestId	Unique request ID to be used to match the specific “Add contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
results	success	“Sucess” status for all successfully processed requests
		id	Contact ID in SmartSender platform. For informational purposes only.
		email	Contact’s email address.
		phone	Contact’s phone number.
		userId	Contact’s unique user ID from your platform
	errors	“Maximum count of records per transaction is 100, current {n}”/td>
		“Argument contactListId must be a non-empty string”/td>
		“Argument webHookUri must be a valid URI”/td>
		“Argument emails must be a list of emails”/td>
		“Each email must be a string”/td>
		“Argument phoneNumbers must be a list of phoneNumbers”/td>
		“Each phoneNumber must be a string”/td>
		“Argument u serIds must be a list of userIds”/td>
		“Each userId must be a string”/td>
		“List with id {contactListId} not found!”/td>
		“add at least one contact to remove”/td>
		“Request saving error. Please, contact us or try again later”/td>
		“Invalid authorization token!”/td>
		“Internal server error”/td>
		“Bad Request”/td>
		“no matches found for access token {accessToken}”/td>
		“user {id} not enabled”/td>
		“no data found for key {userId}”/td>
		“access token check failed for key\/secret $key\/$accessToken”/td>
		“Argument {argument} required”/td>

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'YOUR_WEBHOOK_URL';

$body = json_encode([
   'contactListId' => 'YOUR_CONTACT_LIST_ID',
   'webHookUri'    => 'YOUR_WEBHOOK_URL',
   'emails' => [
       'user-1@example.com',
       'user-2@example.com',
       'user-3@example.com'
   ],
   'phoneNumbers' => [
       '+155555555',
       '+155555556'
   ],
   'userIds' => [
       'myUserId-1',
       'myUserId-2'
   ],
]);

/**
* Documentation Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Access-Token: $accessToken",
'Content-Type: application/json',
'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

Get add/update/remove request status#

To get status of contact add/update/remove request you need to send POST Request to the following URL

http://api.smartsender.io/v3/request/find

Request body:

{
   "ids":[
      "YOUR_REQUEST_ID_1",
      "YOUR_REQUEST_ID_2",
      "YOUR_REQUEST_ID_3"
   ]
}

Parameters
ids `'required'`	List of request ID numbers. You can include `only 100 IDs` in one request.

Response:

{
   "result":true,
   "requests":{
      "YOUR_REQUEST_ID":{
         "id":"YOUR_REQUEST_ID",
         "source":"REQUEST_SOURCE",
         "status":"REQUEST_STATUS",
         "webHookUri":"YOUR_WEBHOOK_URL",
         "createdAt":"YYYY-MM-DD h:i:s",
         "updatedAt":"YYYY-MM-DD h:i:s",
         "results":{
            "errors":[
               {
               "error":"ERROR_CODE",
               "contact":{
                     "id":"SMARTSENDER_CONTACT_ID",
                     "email":"user@example.com",
                     "phone":"+155555555",
                     "userId":"myUserId-1"
                  }
               }
            ],
            "success":[
               {
                  "id":"SMARTSENDER_CONTACT_ID",
                  "email":"user-2@example.com",
                  "phone":"+155555556",
                  "userId":"myUserId-2"
               }
            ]
         }
      }
  },
  "errors":[]
}

Return value
result	The request status
	true	Successfull request
	false	Request failed
	requests	Full information regarding specific request
	YOUR_REQUEST_ID	Unique request ID returned by SmartSender in response to your request.
		id	Unique request ID returned by SmartSender in response to your request.
		source	API method used
			API_CREATE	Add a new contact
			API_UPDATE	Update contact data
			API_REMOVE	Remove a contact
		status	Request current status code
			new	The request is accepted in in processing
			done	The reqeust successfully processed
			fail	The request failed
		webHookUri	Webhook URL included in the reqeust where SmartSender try to send a POST request with the status of the request as soon as it is processed.
		createdAt	Request time in YYYY-MM-DD h:i:s format
		updatedAt	Last time when the information regarding the request was updated in YYYY-MM-DD h:i:s format
		results	An array of information regarding successfull and/or failed contact management requests
			errors	Errors for all failed requests with fail reason description.
				error	ERR_EMPTY_IDENTIFIERS
					ERR_CONTACT_EXISTS
					ERR_CONTACT_DUPLICATION_ATTEMPT
					ERR_SYSTEM_ERROR
					ERR_CONTACT_NOT_EXISTS
					ERR_INVALID_VARIABLE_NAME
				contact	An array of contact information.
					id	Contact ID in SmartSender platform. For informational purposes only.
					email	Contact’s email address.
					phone	Contact’s phone number.
					userId	Contact’s unique user ID from your platform.
			success	An array of contact information.
				id	Contact ID in SmartSender platform. For informational purposes only.
				email	Contact’s email address.
				phone	Contact’s phone number.
				userId	Contact’s unique user ID from your platform.

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Argument ids must be an array of strings”
	“Argument ids can not be empty”
	“ids count must be less or equal 100”
	“each id must be a non-empty string”
	“No matches found”
	“Invalid authoriza tion token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'http://api.smartsender.io/v3/request/find';

$body = json_encode([
    'ids' => [
        'YOUR_REQUEST_ID_1',
        'YOUR_REQUEST_ID_2',
        'YOUR_REQUEST_ID_3'
    ],
]);
echo json_encode(json_decode($body, true), 128) . PHP_EOL;

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

//exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Add Contact List Variable#

To add a new variable to Contact List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contact-list/variables/add

Request body:

{
    "contactListId": "YOUR_CONTACT_LIST_ID",
    "variables": [
        {
            "name": "newVariableName1",
            "type": "ENUM_DATE"
        },
        {
            "name": "newVariableName2",
            "type": "ENUM_STRING"
        }
    ]
}

Parameters
contactListId `'required'`	ID of the contact list to which you want to add the new variable. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
variables `'required'`	Details of variables
	name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
	type `'required'`	`ENUM_STRING`	No specific format required
	name `'required'`	Variable name in lowerCamelCase format `WARNING:` Please use only latin `lowerCamelCase` format. No numbers or other symbols allowed.
	type `'required'`	`ENUM_DATE`	Required format `'YYYY-MM-DD'`

Response:

{
 "result":true
}

Return value
result	The value indicates that the contact was successfully added.
	true	Contact was successfully added

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Maximum count of records per transaction is 100, current {n}”
	“Argument contactListId must be a non-empty string”
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“invalid variable type {type}”
	“Allowed rejectType is {allowed}, but {rejectType} given”
	“List with id {contactListId} not found!”
	“Variable {name} already exists in list {contactListId}”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessT oken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/contact-list/variables/add';

$body = json_encode([
    'contactListId' => 'YOUR_CONTACT_LIST_ID',
    'variables' => [
        [
            "name" => "newVariableName1",
            "type" => "ENUM_DATE", // ENUM_STRING or ENUM_DATE (YYYY-MM-DD)
        ],
        [
            "name" => "newVariableName2",
            "type" => "ENUM_STRING", // ENUM_STRING or ENUM_DATE (YYYY-MM-DD)
        ],
    ],
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Manage Email Black List#

To add | remove | get a email address from Account Email Suppression List you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/blacklist/...

INFO The request body should contain a JSON with the contact details.

Below you can find detailed information on usage of different methods to manage your account Email Black List.

Add A Contact To Email Black List#

To add an email address to account Email Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/blacklist/add

Request body:

{
    "records": [
        {
            "email": "user@example.com",
            "rejectType": "hard",
            "rawLog": "Text to describe reason for adding to Black List"
        }
    ]
}

Parameters
records `'required'`	Array of objects. Each object will be processed and saved. In case of duplicated objects, duplicates will be ignored and no errors will be returned.
	email `'required'`	`IMPORTANT:` should be `valid Email address`.
	rejectType `'required'`	One of available reasons for placing the email address in Email Black List. `WARNING:` Minimum one rejectType (`hard` \| `complaint` \| `list-unsubscribe` ) is required.
		hard	Used to indicate that address is invalid or non existing.
		complaint	Used to indicate that user complaint or asked to unsubscribe.
	rawLog ‘optional’	Optional text description of the reason for placing the contact in suppression list. Up to 1024 symbols.

Response:

{
  "result":true
}

Return value
result	The value indicates that the email address was successfully added to account Email Black List.
	true	Contact was successfully added to Email Black List

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Maximum count of records per transaction is 100, current {n}”
	“Invalid RFC2822 email {email}”
	“Allowed rejectType is {a llowed}, but {rejectType} given”
	“Argument rawLog must be a string”
	“Argument rawLog cannot be longest 1024 bytes”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId} “
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/blacklist/add';

$body = json_encode([
    'records' => [
        [
            "email"  => "user@example.com",
            "rejectType"   => "hard",
            "rawLog" => Text to describe reason for adding to Black List"
        ],
    ],
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Find a contact in Email Black List#

To fetch a email address from account Email Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/blacklist/find

Request body:

{
    "email": "user@example.com",
    "rejectType": "hard",
    "offset": 0,
    "limit": 2
}

Parameters
email `'required'`	Email address. RFC validity not required.
rejectType `'optional'`	Used to indicate that address is invalid or non existing. `WARNING:` Minimum one rejectType (`hard` \| `complaint` \| `list-unsubscribe` ) is required.
	hard	Used to indicate that address is invalid or non existing.
	complaint	Used to indicate that user complaint or asked to unsubscribe.
	list-unsubscribe	Used to indicate that user unsubscribed by list-unsubscribed mechanism.
offset `'optional'`	Integer shift. `Default value`: 0
limit `'optional'`	Integer limit. `Default value`: 20

Response:

{
 "result":true,
 "data":[
  {
   "email":"user@example.com",
   "type":"hard",
   "createdAt":"YYYY-MM-DD h:i:s",
   "expireAt":"YYYY-MM-DD h:i:s"
  }
 ],
 "totalCount":1,
 "offset":0,
 "limit":2
}

Return value
result	The value indicates that the request was successfully and contact information was fetched from account suppression list.
	true
data	Array of objects. Each object contains information on record regarding the requested contact in account Email Black List.
	email	Requested email address
	type	hard	Used to indicate that address is invalid or non existing.
		complaint	Used to indicate that user complaint or asked to unsubscribe.
		list-unsubscribe	Used to indicate that user unsubscribed by list-unsubscribed mechanism.
	created_at	Date, when the requested contact was added to the suppression list. Date format: YYYY-MM-DD h:i:s
	expired_at	Date, when suppression period for the requested contact will automaticaly expire. Date format: YYYY-MM-DD h:i:s
totalCount	Total number of email records in account Email Black List.
offset	Provided integer shift.
limit	Provided integer limit.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Argument email must be a non-empty string”
	“Allowed rejectType is {allowed}, but {rejectType} given”
	“Parameter offset must have a nu meric value”
	“Parameter limit must have a numeric value”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/blacklist/find';

$body = json_encode([
    "email" => "user@example.com",
    "rejectType" => "hard",
    "offset" => 0,
    "limit" => 2,
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}

Remove A Contact From Email Black List#

To remove an email address from account Email Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/blacklist/remove

Request body:

{
    "email": "user@example.com",
    "rejectType": "hard"
}

Parameters
email `'required'`	Contact’s Email address. RFC validity not required.
rejectType `'optional'`	One of available reasons for placing the contact in Email Black List. `WARNING:` Minimum one rejectType (`hard` \| `complaint` \| `list-unsubscribe` ) is required.
	hard `'optional'`	Used to indicate that address is invalid or non existing.
	complaint `'optional'`	Used to indicate that user complaint or asked to unsubscribe.
	list-unsubscribe `'optional'`	Used to indicate that user unsubscribed by list-unsubscribed mechanism.

Response:

{
 "result":true
}

Return value
result	The value indicates that the contact was successfully removed from account Email Black List.
	true	Contact was successfully removed

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Argument email must be a non-empty string”
	“Allowed rejectType is {al lowed}, but {rejectType} given”
	“Invalid authorization token!”,
	“Internal server error”,
	“Bad Request”,
	“no ma tches found for access token {accessToken}”,
	“user {id} not enabled”,
	“no data found for key {userId}”,
	“access token check failed for key\/secret $key\/$accessToken”,
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/blacklist/remove';

$body = json_encode([
    "email"      => "user@example.com",
    "rejectType" => "hard",
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}

Manage Phone Black List#

To add | remove | get a phone number from Account Phone Black List you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/phone-blacklist/...

INFO The request body should contain a JSON with the contact details.

Below you can find detailed information on usage of different methods to manage your account Phone Black List.

Add Contact To Phone Black List#

To add a phone number to account Phone Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/phone-blacklist/add

Request body:

{
   "records": [
      {
         "phoneNumber": "+15555555",
         "rejectType": "invalid"
      }
   ]
}

Parameters
records `'required'`	Array of objects. Each object will be processed and saved. In case of duplicated objects, duplicates will be ignored and no errors will be returned.
	phoneNumber `'required'`	`IMPORTANT:` should be `valid E.164 phone number`.
	rejectType `'required'`	One of available reasons for placing the phone number in Phone Black List. `WARNING:` Minimum one rejectType (`import` \| `invalid` \| `unsubscribe` \| `undeliverable`) is required.
		import	Used to indicate that the phone number was added the the suppression list manually or via API.
		invalid	Used to indicate that phone number is invalid or non existing.
		unsubscribe	Used to indicate that user complaint or asked to unsubscribe.
		undeliverable	Used to indicate that the phone number is unreachable and service is not able to deliver the message.

Response:

{
   "result":true
}

Return value
result	The value indicates that the phone number was successfully added to account Phone Black List.
result	true	Phone number was successfully added

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Maximum count of records per transaction is 100, current {n}”
	“{phoneNumber} is not a valid E.164 phone number”
	“Allowed reject types are {allowed}, but {rejectType} given”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data fou nd for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/phone-blacklist/add';

$body = json_encode([
   'records' => [
      [
         "phoneNumber" => "+15555555",
         "rejectType" => "invalid",
      ],
   ],
]);

/**
* Documentation Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "Access-Token: $accessToken",
   'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
* Request Example
*/
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   "Access-Token: $accessToken",
   'Content-Type: application/json',
   'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
   echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
   echo strval($result) . PHP_EOL;
}
curl_close($ch);

Find A Contact In Phone Black List#

To fetch a phone number from account Phone Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/phone-blacklist/find

Request body:

{
    "phoneNumber": "+1555555",
    "rejectType": "import",
    "offset": 0,
    "limit": 10
}

Return value
phoneNumber `'required'`	`IMPORTANT:` should be `valid E.164 phone number`.
rejectType `'optional'`	One of available reasons for placing the phone number in Phone Black List. `WARNING:` Minimum one rejectType (`import` \| `invalid` \| `unsubscribe` \| `undeliverable`) is required.
	import	Used to indicate that the phone number was added the the suppression list manualy or via API.
	invalid	Used to indicate that the phone number is invalid or non existing.
	unsubscribe	Used to indicate that user complaint or asked to unsubscribe.
	undeliverable	Used to indicate that the phone number is unreachable and service is not able to deliver the message.
offset `'optional'`	Integer shift. `Default value`: 0
limit `'optional'`	Integer limit. `Default value`: 20

Response:

{
 "result":true,
 "data":[
  {
   "phoneNumber":"+15555555",
   "rejectType":"import",
   "createdAt":"YYYY-MM-DD h:i:s"
  }
 ],
 "totalCount":1,
 "offset":0,
 "limit":10
}

Return value
result	The value indicates that the request was successfully and contact information was fetched from account Phone Black List.
	true
data	Array of objects. Each object contains information on record regarding the requested contact in account Phone Black List.
	phoneNumber	Requested phone number
	rejectType	One of available reasons for placing the phone number in Phone Black List.
		import	Used to indicate that the phone number was added the the suppression list manualy or via API.
		invalid	Used to indicate that the phone number is invalid or non existing.
		unsubscribe	Used to indicate that user complaint or asked to unsubscribe.
		undeliverable	Used to indicate that the phone number is unreachable and service is not able to deliver the message.
	createdAt	Date, when the requested contact was added to the Phone Black List. Date format: YYYY-MM-DD h:i:s
totalCount	Total number of contact records in account Phone Black List.
offset	Provided integer shift.
limit	Provided integer limit.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Argument phoneNumber must be a non-empty string”
	“Allowed reject types are {allowed}, but {rejectType} given”
	“Parameter offset must have a numeric value”
	“Parameter limit m ust have a numeric value”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for k ey\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/phone-blacklist/find';

$body = json_encode([
    "phoneNumber" => "+1555555",
    "rejectType"  => "import",
    "offset"      => 0,
    "limit"       => 10,
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Remove A Contact From Phone Black List#

To remove an phone number from account Phone Black List you need to send POST Request to the following URL

https://api.smartsender.io/v3/phone-blacklist/remove

Request body:

{
    "phoneNumber": "+15555555"
}

Parameters
phoneNumber `'required'`	`IMPORTANT:` should be `valid E.164 phone number`.

Response:

{
 "result":true
}

Return value
result	The value indicates that the contact was successfully removed from account Phone Black List.
	true	Contact was successfully removed

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“{phoneNumber} is not a valid E.164 phone number”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argum ent {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url = 'https://api.smartsender.io/v3/phone-blacklist/remove';

$body = json_encode([
    "phoneNumber" => "+15555555",
]);

/**
 * Documentation Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "OPTIONS");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

exit;

/**
 * Request Example
 */
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
//curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_INFILESIZE, null);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen($body),
]);

$result = curl_exec($ch);
if ($result === false) {
    echo 'cURL error:' . curl_error($ch) . PHP_EOL;
} else {
    echo strval($result) . PHP_EOL;
}
curl_close($ch);

Webhooks#

SmartSender can make an HTTP POST request to your URL when events occur with your messages (sent and delivered events are exceptions). If you would like SmartSender to POST event notifications, you need to provide a Callback URL in the the Control Panel.

The SmartSender POST request to your Callback URL will come from following IP address: 188.226.196.117. Please, add it to your Firewall whitelist.

Specific Message Callback Events#

If you have provided webHookUri in your account, SmartSender will send a POST request to it with the status of the Email message.

{
    "datetime": 1234567890,
    "event": "read",
    "email": "user@example.com",
    "id": "5537ab2a08d241dc69326b19",
    "userId": "myUserId-1"
}

Callback URL
datetime	The time when the event was generated in the system provided as Unix epoch seconds.
event	The type of the event.
	read	The email recipient opened the email and enabled image viewing.
	click	The email recipient clicked on a link in the email.
	hard	The ISP server returned hard-bounce for this message
	soft	The ISP server returned soft-bounce for this message
	complaint	The email recipient clicked on a Spam button in his inbox.
	list-unsubscribe	The email recipient requested unsubscription from all emails in his inbox using “list-unsubscribe” technology.
	reject	The email address is in black list
email	The email address of the recipient
id	The message unique identification number in SmartSender system
userId	Contact’s unique user ID from your website from the contactList. `IMPORTANT:` Event with `'reject'` type will not have `'userId'` in the webhook.

Message Delivery Callback Events#

If you have provided webHookUri in your account, SmartSender will send a POST request to it with the status as soon as it is accepted by ISP.

The following are key operational details:

Any webhook batch that does not receive an HTTP 200 response will be retried for a total of 8 hours before the data is discarded.
Webhooks posting to your endpoint will timeout after 10 seconds. For best results, write webhook batches to disk and then process asynchronously to minimize data loss if you have a problem with your database.
One message delivery webhook can be included up to 100 messages. The number is optional and may include less messages.

{
  "event": "delivered",
  "messages": {
    "5537ab2a08d241dc69326b19": {
      "id": "5537ab2a08d241dc69326b19",
      "email": "user@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-1",
      "info": {
        "type": "transaction"
      }
    },
    "5537ab2a08d241dc69326b20": {
      "id": "5537ab2a08d241dc69326b20",
      "email": "user-2@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-2",
      "info": {
        "type": "campaign",
        "id": "59bbcc21f97239a65e546569",
        "title": "campaignName"
      }
    },
    "5537ab2a08d241dc69326b21": {
      "id": "5537ab2a08d241dc69326b21",
      "email": "user-3@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-3",
      "info": {
        "type": "automation",
        "id": "59bbcc21f97239a65e546570"
      }
    }
  }
}

event	The type of the event.
	Delivered	The ISP server returned 250 (accepted & queued for delivery) for this message
messages	Message object where the key is the unique message id and value information on the specific message
	message_id	The message unique identification number in SmartSender system
		id	The message unique identification number in SmartSender system
		email	The email address of the recipient
		datetime	Unix timestamp (seconds from epoch)
		userId	Contact’s unique user ID from your website from the contactList.
		info	Object with additional information
			type	Message type
				transaction	Message was send via API as a transactional
				campaign	Message was send as a one time promo campaign from admin panel
				automation	Message was send from automation set up in admin panel
			id `'optional'`	Available only for messages with campaign or automation types
				campaign_id	The promo campaign unique identification number in SmartSender system
				scenario_id	The automation unique identification number in SmartSender system
			title `'optional'`	The specific campaign name typed in SmartSender during creation. `Important:`Available only for messages with campaign type.

Contact Management Callback Events#

If you have provided webHookUri in your account, SmartSender will send a POST request to it with information regarding changes of the contact status in the Contact List.

{
    "event": "removed",
    "email": "user@example.com",
    "datetime": 1483010763,
    "contactId": "xxx",
    "emailListId": "5537ab2a08d241dc69326b19"
}

Callback URL
event	The type of the event.
	removed	The contact was removed from the specified contact list.
	subscribed	The contact was subscribed to the specified contact list.
	unsubscribed	The contact was unsubscribed from the specified contact list.
email	The email address of the recipient
datetime	The time when the event was generated in the system provided as Unix epoch seconds.
contactId	The message unique identification number for the contact in SmartSender system
emailListId	ID of the email list to which you want to add the new variable. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
Variable for unsubscribe	This webhook will work only if unsubscribes are handled by SmartSender via variable {{unSubscribeUrl}}

SMS Delivery Status#

If you have provided webHookUri in your account, SmartSender will send a POST request to it with the status of the SMS as soon as it is accepted by Mobile Operator.

{
   "datetime":     1234567890,
   "event":       "sms_delivered",
   "phoneNumber": "+155555555",
   "id":          "5537ab2a08d241dc69326b19"
}

Callback URL
datetime	Request time in `Unix_Timestamp` format
event	The type of the event.
event	sms_delivered	The SMS was successfully delivered to recipient.
phoneNumber	Addressee phoneNumber.
id	The SMS unique identification number in SmartSender system