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,
]);

/**
* 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.
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'
     ]
  ],
 ]);

/**
* 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',
   ],
   ]);

 /**
 * 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',
   ],
]);

/**
* 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'
        ],
    ],
]);

/**
 * 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',
    ],
]);

/**
 * 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
]);

/**
 * 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
]);

/**
 * 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'
    ],
]);

/**
 * 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',
]);

/**
 * 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"
   ]
}

“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”

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”

PHP Example

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

/**
 * 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"    
   ]    
}

“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”

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”

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.
]);

/**
 * 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',
]);

/**
 * 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.
WARNINGMinimum 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' 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",
                ],
            ],
        ],
    ],
]);

/**
 * 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.
WARNINGMinimum 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' 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",
                ],
            ],
        ],
    ],
]);

/**
 * 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.
WARNINGMinimum 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'
   ],
]);

/**
* 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'
    ],
]);

/**
 * 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)
        ],
    ],
]);

/**
 * 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"
        ],
    ],
]);

/**
 * 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
}
email
'required'Email address. RFC validity not required.

Parameters
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,
]);

/**
 * 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",
]);

/**
 * 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.
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",
      ],
   ],
]);

/**
* 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,
]);

/**
 * 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",
]);

/**
 * 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.
sms_delivered The SMS was successfully delivered to recipient.
phoneNumber Addressee phoneNumber.
id The SMS unique identification number in SmartSender system

We use cookies to make SmartSender’s website a better place. Cookies help to provide a more personalized experience for you, and web analytics for us. To learn more, and to see a full list of cookies we use, check out our Cookie Policy (baked goods not included).

got it