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 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!",
    "ignoreBlackList": true,
    "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.
ignoreBlackList
'optional'		 By setting the filter to true, your message will bypass all unsubscribes and suppressions in all lists.
ignoreHard
'optional'		 By setting the filter to true, your message will bypass the bounce list.
The spam report and global unsubscribe lists will be checked and respected.
ignoreComplaint
'optional'		 By setting the filter to true, your message will bypass the spam report list.
The bounce and global unsubscribe lists will be checked and respected.
ignoreUnsubscribe
'optional'		 By setting the filter to true, your message will bypass the global unsubscribe list.
The spam report and bounce lists will be checked and respected.
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). IMPORTANTHeaders should start with X-
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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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",
 "ignoreBlackList": true,
 "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/
ignoreBlackList
‘optional’		 By setting the filter to true, your message will bypass all unsubscribes and suppressions in all lists.
ignoreHard
'optional'		 By setting the filter to true, your message will bypass the bounce list.
The spam report and global unsubscribe lists will be checked and respected.
ignoreComplaint
‘optional’		 By setting the filter to true, your message will bypass the spam report list.
The bounce and global unsubscribe lists will be checked and respected.
ignoreUnsubscribe
‘optional’		 By setting the filter to true, your message will bypass the global unsubscribe list.
The spam report and bounce lists will be checked and respected.
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: Variable 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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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 messageId you need to send POST Request to the following URL

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

Request body:

{
 "ids": [
     "YOUR_messageId_1",
     "YOUR_messageId_2",
     "YOUR_messageId_3"
 ]
}
Parameters
ids
'required'		 List of messageId 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:
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.

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 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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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: Variable 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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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 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":           "3600"
}
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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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": "3600" 
}
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”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“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);

Send Telegram Message#

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

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

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

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

Send Telegram message#

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

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

Request body

{
  "botId": "YOUR_TELEGRAM_BOT_ID",
  "contact": "user@example.com",
  "content": [
    {
      "type": "text",
      "text": "TELEGRAM_CONTENT_TEXT",
      "buttons": [
        {
          "text": "Title of button",
          "link": "FINAL_DESTINATION_URL"
        }
      ]
    },
    {
      "type": "file",
      "file": "ICON_file_URL"
    },
    {
      "type": "image",
      "image": "ICON_IMAGE_URL"
    }
  ],
  "tags": [
    "tag1",
    "tag2"
  ]
}
Parameters
botId
'required'		 Unique Telegram botId that is already registered
contact
'required'		 The ’email’ address,‘userId’ or ‘phoneNumber’ of the recipient stored in the corresponding contactList.
content
'required'		 Telegram message content that you want to send. You have several types of blocks for creating messages. 
type text
‘optional’		 text
'required'		 Telegram content text you want to send.
'required'
buttons
‘optional’
Important: Using a button without text block is not possible		 text
'required'		 Text for button name
link
'required'		 Link to the page where subscribers will get when they click on the link
type file
‘optional’		 You can attach a file for you  message
file
'required'		 Link to the file will be downloaded by subscribers when they click on the link.
type image
‘optional’		 Shows image in a telegram message
image
'required'		 Link to the image will be shown to subscribers when the message is delivered
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.
WARNING: Any tags starting with an underscore are reserved for internal use and will cause errors.

Response:

{
   "result":true,
   "telegram_message_ids":["5d914c3dd132d5f45a4e3670"]
}
Return Value the sending results for a single recipient
telegram_message_ids 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 “Argument botId must be a non-empty string”
“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
“Argument content must be an array”
“Argument content must be a non-empty array”
“Argument type in template row {templateRowNum} must be present”
 “Unknown type {type} in template row {templateRowNum}”
“Argument text must be present in template row {templateRowNum}”
“Argument text must be non-empty in template row {templateRowNum}”
“Argument text can be {limit} characters length”
 “Argument button text must be present in template row {templateRowNum}, button number {buttonNum}”
“Argument button text must be non-empty in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be present in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be non-empty in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be a valid link in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be a valid HTTP\/HTTPS link in template row {templateRowNum}, button number {buttonNum}”
“Argument image must be present in template row {templateRowNum}”
“Argument image must be non-empty in template row {templateRowNum}”
“Argument image must be a valid image url in template row {templateRowNum}”
“Argument image must be a valid image url over HTTPS in template row {templateRowNum}”
“Argument file must be present in template row {templateRowNum}”
“Argument file must be non-empty in template row {templateRowNum}”
 “Argument file must be a valid image url in template row {templateRowNum}”
 “Argument file must be a valid image url over HTTPS in template row {templateRowNum}”
“Argument tags must be an array of strings”
“Tag name must be a non-empty string”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“Bot {botId} doest not have contact list”
“Argument botId must be a non-empty string”
“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
“Argument content must be an array”
“Argument content must be a non-empty array”
“Argument type in template row {templateRowNum} must be present”
“Unknown type {type} in template row {templateRowNum}”
“Argument text must be present in template row {templateRowNum}”
“Argument text must be non-empty in template row {templateRowNum}”
 “Argument text can be {limit} characters length”
“Argument button text must be present in template row {templateRowNum}, button number {buttonNum}”
“Argument button text must be non-empty in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be present in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be non-empty in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be a valid link in template row {templateRowNum}, button number {buttonNum}”
“Argument button link must be a valid HTTP\/HTTPS link in template row {templateRowNum}, button number {buttonNum}”
“Argument image must be present in template row {templateRowNum}”
“Argument image must be non-empty in template row {templateRowNum}”
“Argument image must be a valid image url in template row {templateRowNum}”
“Argument image must be a valid image url over HTTPS in template row {templateRowNum}”
“Argument file must be present in template row {templateRowNum}”
“Argument file must be non-empty in template row {templateRowNum}”
“Argument file must be a valid image url in template row {templateRowNum}”
“Argument file must be a valid image url over HTTPS in template row {templateRowNum}”
“Telegram not allowed for your account”
“Telegram bot {bot} not found”
“Contact with {contact} not found”
“Contact {contact} is not subscribed to bot”
 “Contact {contact} is not subscribed to telegram channel”
“Payment required”
“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/telegram/send';
$body        = json_encode([
    "botId"   => "YOUR_TELEGRAM_BOT_ID",
    "contact" => "user@example.com",
    "content" => [
        [
            "type"    => "text",
            "text"    => "TELEGRAM_CONTENT_TEXT",
            "buttons" => [
                [
                    "text" => "Title of button_first",
                    "link" => "FINAL_DESTINATION_URL",
                ],
                [
                    "text" => "Title of button_second",
                    "link" => "FINAL_DESTINATION_URL",
                ],
            ],
        ],
        [
            "type" => "file",
            "file" => "ICON_file_URL_FIRST",
        ],
        [
            "type" => "file",
            "file" => "ICON_file_URL_SECOND",
        ],
        [
            "type"  => "image",
            "image" => "ICON_IMAGE_URL_FIRST",
        ],
        [
            "type"  => "image",
            "image" => "ICON_IMAGE_URL_SECOND",
        ],
    ],
    "tags"    => [
        "TelegramTag1",
        "TelegramTag2",
    ],
]);
/**
 * 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 Telegram message#

To send a triggered Telegram message, you need to send POST Request to the following URL.

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

Request body:

{
  "botId": "YOUR_TELEGRAM_BOT_ID",
  "contact": "user@example.com",
  "templateId": "YOUR_TELEGRAM_TEMPLATE_ID",
  "variables": [
    {
      "name": "variableName",
      "value": "variableValue"
    },
    {
      "name": "newVariableName2",
      "value": "YYYY-MM-DD"
    }
  ],
  "tags": [
    "triggerTag1",
    "triggerTag2"
  ]
}
Parameters
botId
'required'		 Unique Telegram botId that is already registered
contact
'required'		 The 'email' address, 'userId' or 'phoneNumber' of the recipient stored in the corresponding contactList
templateId
'required'		 The Telegram template you want to send. The template should be already created in your account on the Templates page:
https://partner.smartsender.io/templates-telegram/
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'		 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.
WARNING:Any tags starting with an underscore are reserved for internal use and will cause errors.

Response:

{
"result":true,
"telegram_message_ids":["5e1c888bd132d5e7d00f17f8"]
}
Return value
result The value indicates that the triggered message was successfully sent out.
true Message was successfully sent out.
telegram_message_ids 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 botId must be a non-empty string”
“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
“Argument templateId must be a non-empty string”
“Telegram template {templateId} not found”
“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”
“invalid name of variable {name}”
“Telegram template {templateId} not found”
“Bot {botId} does not have contact list”
“Argument botId must be a non-empty string”
“Argument contact must be a non-empty string filled with valid email, phoneNumber or userId”
“Argument tags must be an array”
“Tag name must be a non-empty string”
“Tags should be 50 characters or less”
“Any tags starting with an underscore are reserved for internal use and will cause errors”
“Telegram not allowed for your account”
“Telegram bot {bot} not found”
“Contact with {contact} not found”
“Contact {contact} is not subscribed to bot”
“Contact {contact} is not subscribed to telegram channel”
“Payment required”
“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” 
$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/telegram/trigger';
$body        = json_encode([
    "botId"      => "YOUR_TELEGRAM_BOT_ID",
    "contact"    => "user@example.com",
    "templateId" => "YOUR_TEMPLATE_ID",
    "variables"  => [
        [
            'name'  => 'variableName1',
            'value' => 'variableValue',
        ],
        [
            'name'  => 'variableName2',
            'value' => 'YYYY-MM-DD',
        ],
    ],
    "tags"       => [
        "triggerTag1",
        "triggerTag2",
    ],
]);
/**
 * 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 Telegram Message Status#

To get a Telegrsm message status by Telegram message_id, you need to send POST Request to the following URL:

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

Request body:

{
  "ids": [
    "YOUR_TELEGRAM_MESSAGE_ID_1",
    "YOUR_TELEGRAM_MESSAGE_ID_2", 
    "YOUR_TELEGRAM_MESSAGE_ID_3"
  ]
}
Parameters
ids
'required'		 List of message ID numbers. You can include only 100 IDs in one request.

Response:

{
  "result": true,
  "telegram_messages": [
    {
      "id": "YOUR_TELEGRAM MESSAGE_ID_1",
      "status": "delivered",
      "to": {
        "name": "userName",
        "email": "user@example.com"
      },
      "events": [
        {
          "event": "delivered",
          "datetime": "YYYY-MM-DD h:i:s"
        },
        {
          "event": "click", 
          "datetime": "YYYY-MM-DD h:i:s"
        },
        {
          "event":"viewed",
          "datetime": "YYYY-MM-DD h:i:s"
        }
                ]
      }
   ]
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
telegram_messages id The message unique identification number in SmartSender system
status The message unique identification number in SmartSender system
delivered The telegram message was delivered
fail The telegram message wasn’t delivered ( if contact unsubscribed from the bot
through “stop and block bot” function)
to An array of recipient information.
name The optional display name of the recipient
email The email address of the recipient
events Telegram messages statistics includes detailed information on each messages in the account. List of available events:
viewed The status is assigned as soon as the user viewed the message.
delivered The messages was delivered
click The status is assigned every time URLs have been clicked by the user

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/telegram/info';
$body        = json_encode([
    'ids' => [
        'first-id',
        'second-id',
    ],
]);
/**
 * 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 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 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 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",
            "customerSourceId": "mySourceID",
            "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
customerSourceId
‘optional’		 Contact’s unique source ID from your system to synchronize two sides
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",
            "customerSourceId" => "mySourceId",
            "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": "Source_ID_from_SmartSender",
      "customerSourceId": "Customer_Source_ID_From_Your_Platform",
      "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
customerSourceId
‘optional’		 Contact’s unique source ID from your system to synchronize two sides

Important: If you use sourceId and customerSourceId at the same time, sourceId will be  priority
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", 
            "customerSourceId" => "mySourceId",
            "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 = 'https://api.smartsender.io/v3/contacts/remove';

$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

https://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 = 'https://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 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 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 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 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);

Manage Contact Source#

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

https://api.smartsender.io/v3/contact-source/...

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

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

Add Source#

To register a new contact source you need to send POST Request to the following URL:

https://api.smartsender.io/v3/contact-source/add

Request body:

{
"name": "SourceName",
"customerSourceId": "mySourceID",
"cac": {
          "value": 2.05,
          "currency": "EUR" 
        }
}
Parameters
name
'required'		 Name of your contact source
‘customerSourceId’
‘optional’		 Unique customerSourceId that is already registered in your system.
WARNING: Please use only latin format.  No symbols allowed.
INFO Defaults:
When creating a new source, we assign it a Unique sourceId in the SmartSender system, which you can also use in API
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,
 "sourceId":"5d915c22d132d5f45a4e38b8"
}
Return value
result The value indicates that the source was successfully added to your account.
true Source was successfully added
sourceId Unique source ID assigned in the SmartSender system is used to match the specific “Add source”. It will be sent by SmartSender after the request was processed.

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 ‘name’ must be a non-empty string with max length 150 chars”
“Argument ‘customerSourceId’ must be an alphanumeric string with max length 40 chars”
“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.”
“Contact source with this parameters is already registered”
“Invalid authorization token!”
“Internal server error”
“Bad Request”
“no matches found for access token”
“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-source/add";
$body = json_encode([ 
    'name'             => 'SourceName',
    'customerSourceId' => 'mySourceID',   
    'cac'              => [          
        'value'    => 0.05,
        'currency' => 'USD',
    ],
]);
/**
 * 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 Source#

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

https://api.smartsender.io/v3/contact-source/update

Request body:

{
"source": "sourceId or customerSourceId",
"name": "SourceName",
"customerSourceId": "myNewSourceID",
"cac": {
          "value": 2.05,
          "currency": "EUR" 
        }
}
Parameters
source
'required'		 Unique customerSourceId or sourceId that is already registered in SmartSender system.
name
‘optional’		 Name of your contact source
customerSourceId
‘optional’		 New unique customerSourceId that is already registered in your system.
WARNING: Please use only latin format.  No symbols allowed.
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
}
Return value
result The value indicates that the source was successfully updated in your account.
true Source was successfully updated

Example Error Response JSON:

{
   "result":false,
   "errors":[
      "Error description text"
   ]
}
Errors.
The reason for the rejection.
result The status of the request.
true The request is accepted and queued
false The request is rejected
errors “Argument ‘source’ must be a non-empty string: ID or customerSourceId of updating instance”
“Argument ‘name’ must be a non-empty string with max length 150 chars”
“Argument ‘customerSourceId’ must be an alphanumeric string with max length 40 chars”
“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”
“Argument ‘source’ required”,”Contact source {source} not found in your account”
“Contact source with this parameters is already registered”
“Invalid authorization token!”
“Internal server error”
“Bad Request”
“no matches found for access token {accessToken}”
“user {id} not enabled”
“access token check failed for key\/secret $key\/$accessToken”
“Argument {argument} required”
“no data found for key {userId}”

PHP Example:

$accessToken = 'YOUR_API_KEY';
$url         = 'https://api.smartsender.io/v3/contact-source/update';
$body = json_encode([
    'source'           => 'sourceId or customerSourceId',                     
    'name'             => 'SourceName',
    'customerSourceId' => 'myNewSourceID', 
    'cac'              => [       
        'value'    => 2.05,
        'currency' => 'USD',
    ],
]);
/**
 * 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 Source#

To remove a contact source from account you need to send POST Request to the following URL

https://api.smartsender.io/v3/contact-source/remove

Request body:

{
    "ids":[
      "YOUR_sourceId_1",
      "YOUR_sourceId_2"
   ],
    "customerSourceIds": [
      "YOUR_customerSourceId_1",
      "YOUR_customerSourceId_2"
   ]
}
Parameters
ids
‘optional’		 Unique sourceId that is already registered in the system.
customerSourceIds
‘optional’		 Unique customerSourceId that is already registered in the system.

Response:

{
    "result": true,
    "affectedRows":1
}
Return value
result The value indicates that the source was successfully removed in your account.
true Source was successfully removed
affectedRows The number of sources that were removed in the request

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 ids must be an array of strings”
“Argument customerSourceIds must be an array of strings”
“Each customerSourceId must be an alphanumeric string with 40 max chars length”
“Add at least one identifier to remove”
“No records found by this identifiers”
“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/contact-source/remove';
$body = json_encode([
    'ids'               => [
        "YOUR_sourceId_1",
        "YOUR_sourceId_2",
    ],
    'customerSourceIds' => [
        "YOUR_customerSourceId_1",
        "YOUR_customerSourceId_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);

Find Source#

To find all contact sources you need to send POST Request to the following URL

https://api.smartsender.io/v3/contact-source/find

Request body:

{
"name": "SourceName",
"customerSourceId": "mySourceID",
"offset" : "0",
"limit" : "20"
}
Parameters
name
‘optional’		 Unique sourceId that is already registered in the system.
customerSourceId
‘optional’		 Unique customerSourceId that is already registered in the system.
offset
‘optional’		 Allows you to omit a specified number of rows (number of source) before the beginning of return rows (source) from the query
limit
‘optional’		 The limit option allows you to limit the number of rows returned from a query.

Response:

{
 "result":true,
 "data":[
            {
               "id":"5f8446cb9a0a716b250a117e",
               "name":"sourceName 2020-10-12 15:06:35",
               "customerSourceId":"apiId_9",
               "cac":{ 
                       "value":"5.00000",
                       "currency":"USD"
                      },
               "createdAt":"2020-10-12 12:06:35",
               "updatedAt":"2020-10-12 12:06:35"
             }
          ],
 "totalCount":1,
 "offset":0,
 "limit":20
}
Return value
result The value indicates that the source was successfully get in your account.
true Source was successfully found
data id sourceId in the SmartSender system
name sourceName and creation date
customerSourceId Customer source Id already registred in SmartSender system
cac value CAC value in string format
currency (EUR, USD)
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
totalCount The number of sources that could be unloaded
offset The number of sources to view, from…
limit The number of sources to view, to…

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 name must be a non-empty string”]},”customerSourceId”
“Argument ‘customerSourceId’ must be an alphanumeric string with max length 40 chars”
“Argument offset must have a numeric value”
“Argument 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” 
$accessToken = 'YOUR_API_KEY';
$url         = 'https://api.smartsender.io/v3/contact-source/find';
$body = json_encode([
    'name'             => 'SourceName',
    'customerSourceId' => 'YOUR_customerSourceId',
    'offset'           => 0,
    'limit'            => 20,]);
/** * 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 Events#

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

https://api.smartsender.io/v3/custom-event/...

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

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

Add Event#

To add a custom event to the contacts you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/custom-event/add

Request body:

{
  "domain": "senderDomain.com",
  "customEvent": "YOUR_REGISTERED_EVENT_ID or EVENT_NAME",
  "contact": "user@example.com",
  "dateTime": "2020-11-01T19:30:22+02:00", 
  "ipAddress": "127.0.0.1",
  "userAgent": "Chrome/85.0.4183.121",
  "httpReferer": "https://some.link/some-path?some=query",
  "utmSource":"traffic_source",
  "utmMedium": "traffic type",
  "utmCampaign": "advertising campaign",
  "utmContent": "content",
  "utmTerm": "keyword",
  "cost": { 
            "value": 2.05,
            "currency": "EUR"
          }
}

Parameters
domain
'required'		 Verified domain name from your SmartSender account. This data is used to send your webhooks and generate reports.
customEvent
'required'		 Unique EventId or EventName that is already registered in SmartSender system.
contact
'required'		 The ’email’ address, ‘userId’ or ‘phoneNumber’ of the recipient stored in the DefaultContactList.
dateTime
‘optional’		 Date and time when the event occurred. Format DateTime: ISO8601
INFO Defaults:
If the time and date of the events are empty, we put down the date and time of adding the event to the SmartSender system.
ipAddress
‘optional’		 IP address is an identifying number that is associated with a specific computer or computer network.
Is used to target consumers on a specific internet network, by sending advertisements to the IP addresses accessing that network.IpAddress value in 'ENUM_STRING' format correspondingly.
userAgent
‘optional’		 A browser’s user agent string identify which browser is used, what version, and on which operating system.
UserAgent value in 'ENUM_STRING' format correspondingly.Example: “Mozilla/5.0 (X11; Linux x86_64)”, “AppleWebKit/537.36 (KHTML, like Gecko)”, “Chrome/85.0.4183.121”,  “Safari/537.36”
httpReferer
‘optional’		 Optional HTTP header field that identifies the address of the webpage which is linked to the resource being requested.

httpReferer value in 'ENUM_STRING' format correspondingly.
utmSource
‘optional’		 Traffic source
For example: Direct, Adwords, website
utmMedium
‘optional’		 Traffic type
It can be contextual advertising, social media advertising, 
banner advertising, advertising on price aggregators, retargeting sites, 
CPA networks, email newsletters.
utmCampaign
‘optional’		 Advertising campaigns
name of the ad campaign
utmContent
‘optional’		 This tag is filled arbitrarily, banner text
utmTerm
‘optional’		 Keyword
Manually set a keyword,  specified a dynamic parameter, which will be replaced by a keyword.
cost
‘optional’		 value
'required'		  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
}
Return value
result The value indicates that the event was successfully added to your account.
true The event was successfully added to the contact

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Argument 'ipAddress' must be a valid IPv4 address"
   ]
}
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 domain must be a non-empty string”
“Domain {domain} not found in your account”
“Argument ‘customEvent’ must be an alphanumeric string with max length 40 chars”
“Custom event {customEvent} not found in your account”
“Argument ‘contact’ must be a non-empty string”
“Invalid ‘dateTime’ parameter”
“Argument ‘ipAddress’ must be a valid IPv4 address”
“Argument ‘httpReferer’ must be a valid URL”
“Argument ‘utmSource’ must be a non-empty string”
“Argument ‘utmMedium’ must be a non-empty string”
“Argument ‘utmCampaign’ must be a non-empty string”
“Argument ‘utmContent’ must be a non-empty string”
“Argument ‘utmTerm’ must be a non-empty string”
“Argument ‘cost’ must be an array with value and currency fields”
“Cost value must be a positive float”
“Cost currency {currency} not allowed. USD, EUR are.”
“Custom event with this parameters is already registered”
“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/custom-event/add';
$body = json_encode([
    'domain'      => 'senderDomain.com',       
    'customEvent' => 'YOUR_REGISTERED_EVENT_ID or EVENT_NAME', 
    'contact'     => 'user@example.com',  
    'dateTime'    => '2020-11-01T19:30:22+02:00',
    'ipAddress'   => '127.0.0.1',  
    'userAgent'   => 'Mozilla/5.0 (X11; Linux x86_64)',
    'httpReferer' => 'https://some.link/some-path?some=query',
    'utmSource'   => 'traffic_source',   
    'utmMedium'   => 'traffic type',   
    'utmCampaign' => 'advertising campaign', 
    'utmContent'  => 'content',  
    'utmTerm'     => 'keyword',     
    'cost'        => [         
        'value'    => 0.06,     
        'currency' => 'USD', 
    ],
]);
/**
 * 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 Event#

To remove a custom event in the Event List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/custom-event/remove

Request body:

{
  "ids":  [
      "YOUR_registred_eventId_1",
      "YOUR_registred_eventId_2"
          ],
  "names":[ 
      "YOUR_registred_eventName_1", 
      "YOUR_registred_eventName_2" 
          ]
}

Parameters
ids
‘optional’		 Unique EventIds that are already registered in the SmartSender system.
names
‘optional’		 Unique EventNames that are already registered in the SmartSender system.

Response:

{
 "result":true,
 "affectedRows":1
}
Return value
result The value indicates that the event was successfully removed from your account
true Event was successfully removed
affectedRows The number of events that were removed from the SmartSender system

Example Error Response JSON

{
   "result":false,
   "errors":[
      "No records found by this identifiers"
   ]
}
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 names must be an array of strings”
“Each names must be an alphanumeric string with 40 max chars length”
“Add at least one identifier to remove”
“No records found by this identifiers”
“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 = $host . '/v3/custom-event/remove';
$body = json_encode([
    'ids' => [      
        'id1', 'id2'
    ],
    'names' => [  
        'ApiEvent_1_updated', 'name2'
    ],
]);
/**
 * 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 Event#

To update a custom event in the Event List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/custom-event/update

Request body:

{
  "customEvent": "YOUR_REGISTERED_EVENT_ID or EVENT_NAME",
  "name": "New_EVENT_NAME",
  "description": "New_EVENT_DESCRIPTION",
  "isConversion": true,
  "cost": { 
            "value": 2.05,
            "currency": "EUR"
           }
}

Parameters
customEvent
'required'		 Unique EventId or EventName that is already registered in SmartSender system.
name
‘optional’		 Changes EventName. It must be unique
description
‘optional’		 Description note about your events
isConversion
‘optional’		 If you want existing events to be taken into account in advanced analytics, mark the parameter as true or false if not.
cost
‘optional’		 value
'required'		 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
}
Return value
result The value indicates that the event was successfully updated to your account.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Argument customEvent 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 “Argument ‘customEvent’ must be a non-empty string: ID or name of updating instance”
“Argument ‘name’ must be a non-empty alphanumeric string with a max length of 40 chars”
“Argument ‘description’ must be a non-empty string with max length 1000 chars”
“Argument ‘isConversion’ must be a boolean”
“Argument ‘cost’ must be an array with value and currency fields”
“Cost value must be a positive float”
“Cost currency {currency} not allowed. USD, EUR are.”
“Argument ‘customEvent’ required”,”Custom event {customEvent} not found in your account”
“Custom event with this parameter is already registered”
“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/custom-event/update'; 
$body = json_encode([ 
    'customEvent'  => 'YOUR_REGISTERED_EVENT_ID or EVENT_NAME',  
    'name'         => 'New_EVENT_NAME', 
    'description'  => 'New_EVENT_DESCRIPTION', 
    'isConversion' => true,  
    'cost'         => [                
         'value'    => 0.06, 
         'currency' => 'USD',
    ],
]);
/**
 * 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);

Create Event#

To create a custom event in the Event List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/custom-event/create

Request body:

{
  "name": "YOUR_EVENT_NAME",
  "description": "YOUR_CUSTOM_DESCRIPTION",
  "isConversion": true,
  "cost": {
              "value": 2.05, 
              "currency": "EUR"
           }
}

Parameters
name
'required'		 Unique  EventName for registering in SmartSender system.
description
‘optional’		 Description note about your events
isConversion
‘optional’		 If you want existing events to be taken into account in advanced analytics, mark the parameter as true or false if not.
cost
‘optional’		 value
'required'		 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,
 "id":"5d915c22d132d5f45a4e38b8"
}
Return value
result The value indicates that the event was successfully added to your account. 
true Event was successfully registred
Id Unique event ID assigned in the SmartSender system is used to match the specific “Add event”. It will be sent by SmartSender after the request was processed.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Custom event with this parameter is already registered"
   ]
}
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 ‘name’ must be a non-empty alphanumeric string with a max length of 40 chars”
“Argument ‘description’ must be a non-empty string with max length 1000 chars”
“Argument ‘isConversion’ must be a boolean”
“Argument ‘cost’ must be an array with value and currency fields”
“Cost value must be a positive float”
“Cost currency {currency} not allowed. USD, EUR are.”
“Custom event with this parameter is already registered”
“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/custom-event/create';
$body = json_encode([
    'name'         => 'YOUR_EVENT_NAME', 
    'description'  => 'YOUR_CUSTOM_DESCRIPTION', 
    'isConversion' => true, 
    'cost'         => [    
        'value'    => 0.05,
        'currency' => 'USD',
    ],
]);
/**
 * 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 Event#

To find a custom event in the Events List you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/custom-event/find

Request body:

{
  "id": "YOUR_REGISTERED_EVENT_ID",
  "name": "YOUR_REGISTERED_EVENT_NAME",
  "offset": "0",
  "limit": "20"
}

Parameters
id
‘optional’		 Unique EventId that is already registered in SmartSender system.
name
‘optional’		 Unique EventName that is already registered in SmartSender system.
offset
‘optional’		 Allows you to omit a specified number of rows (number of events) before the beginning of return rows (events) from the query.
limit
‘optional’		 Allows you to limit the number of rows (events) returned from a query.

Response:

{
 "result":true,
 "data":[{
            "id":"YOUR_eventId_1",
            "name":"YOUR_EventName",
            "description":"",
            "isConversion":true,
            "cost":{
                      "value":"91.00",
                      "currency":"EUR"
                    },
            "createdAt":"2020-11-06 13:57:53",
            "updatedAt":"2020-11-06 13:57:53"
          }],
"totalCount":1,
"offset":0,
"limit":20
}
Return value
result The value indicates that the event was successfully found in your account.
true Event was successfully found
data id eventId in the SmartSender system
name eventName in the SmartSender system
description Description note about your events
isConversion If you want existing events to be taken into account in advanced analytics, mark the parameter as true or false if not.
cost Value and currency of your registered event
createdAt Creation time of the event in YYYY-MM-DD h:i:s format
updatedAt Last time when the information of the event was updated in YYYY-MM-DD h:i:s format
totalCount The number of events that were found in the request
offset Allows you to omit a specified number of rows (number of events) before the beginning of return rows (events) from the query.
limit Allows you to limit the number of rows (events) returned from a query.

Example Error Response JSON

{
   "result":false,
   "errors":[
      "Argument 'id' must be a non-empty alphanumeric string (MongoID)"
   ]
}
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 ‘id’ must be a non-empty alphanumeric string (MongoID)”
“Argument ‘name’ must be a non-empty alphanumeric string with a max length of 40 chars”
“Argument offset must have a numeric value”
“Argument 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/custom-event/find';
$body = json_encode([
    'id'     => 'YOUR_REGISTERED_EVENT_ID', 
    'name'   => 'YOUR_REGISTERED_EVENT_NAME',
    'offset' => 0, 
    'limit'  => 20, 
]);
/**
 * 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;
    $decoded = json_decode($result, true);
    if(isset($decoded['data'])) {
        foreach($decoded['data'] as $i => $sourceData) {
            echo $i . ' => ' . $sourceData['name'] . 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"
    "headers": {
        "X-Additional-Header": "additional-header-value"
    }
}
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 userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
headers Optional extra headers added to the message.

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": "60890ee5890ede9d2c70a077",
    "emailListId": "5537ab2a08d241dc69326b19",
    "phoneNumber": "+155555555",
    "userId": "myUserId-1"
}
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 The ID of the contact list to which the contact belongs.
The contact list already should be created in your account on the Lists page:
https://partner.smartsender.io/email-list/
phoneNumber Addressee phoneNumber.
userId Contact’s unique userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
Variable for unsubscribe This webhook will work only if unsubscribes are handled by SmartSender via variable {{unSubscribeUrl}}

Email Delivery Status#

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"
      },
      "headers": {
          "X-Additional-Header": "additional-header-value"
      }
    },
    "5537ab2a08d241dc69326b20": {
      "id": "5537ab2a08d241dc69326b20",
      "email": "user-2@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-2"
      "info": {
        "type": "campaign",
        "id": "59bbcc21f97239a65e546569",
        "title": "campaignName"
      },
      "headers": {
          "X-Additional-Header": "additional-header-value"
      }
    },
    "5537ab2a08d241dc69326b21": {
      "id": "5537ab2a08d241dc69326b21",
      "email": "user-3@example.com",
      "datetime": 1510676506,
      "userId": "myUserId-3"
      "info": {
        "type": "automation",
        "id": "59bbcc21f97239a65e546570"
      }
     "headers": null
    }
  }
}
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 userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
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.
headers Optional extra headers added to the message.

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",
   "userId": "myUserId-1",
   "email": "user@example.com",
   "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.
userId Contact’s unique userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email The email address of the recipient
id The SMS unique identification number in SmartSender system

Telegram Delivery Status#

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

{
  "datetime": 1234567890,
  "event": "telegram-delivered",
  "id": "5537ab2a08d241dc69326b19",
  "botId": "60891092890ede99356891u7",
  "contactId": "60890ee5890ede9d2c70a077",
  "emailListId": "60224b6a890ededbb63493yy",
  "phoneNumber": "+155555555",
  "userId": "myUserId-1",
  "email": "user@example.com"
}
Callback URL
datetime Request time in Unix_Timestamp format
event The type of the event.
telegram-delivered The message was successfully delivered to the recipient.
telegram-viewed The recipient opened the message
telegram-clicked The email recipient clicked on a link in the message.
id The Telegram message unique identification in the SmartSender system
botId Unique Telegram botId that is already registered
contactId The  unique identification number for the contact in the SmartSender system
emailListId The ID of the contact list to which the contact belongs.
The contact list already should be created in your account on the Lists page:
https://partner.smartsender.io/email-list/
phoneNumber Addressee phoneNumber.
userId Contact’s unique userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email The email address of the recipient

WebPush Delivery Status#

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

{
  "datetime": 1234567890,
  "event": "telegram-delivered",
  "id": "5537ab2a08d241dc69326b19",
  "webSiteId": "60379473a813802d276922b1"
  "contactId": "60890ee5890ede9d2c70a02d",
  "emailListId": "60224b6a890ededbb63493ee",
  "phoneNumber": "+155555555",
  "userId": "myUserId-1",
  "email": "user@example.com"
}
Callback URL
datetime Request time in Unix_Timestamp format
event The type of the event.
webPush-delivered The message was successfully delivered to the recipient.
webPush-open The recipient opened the message
webPush-clicked The email recipient clicked on a link in the message.
id The webPush message unique identification in the SmartSender system
webSiteId Unique Website Id that is already registered
contactId The  unique identification number for the contact in the SmartSender system
emailListId The ID of the contact list to which the contact belongs.
The contact list already should be created in your account on the Lists page:
https://partner.smartsender.io/email-list/
phoneNumber Addressee phoneNumber.
userId Contact’s unique userId from your platform enables management of the contact in the list based on it.

IMPORTANT: The userId should be added beforehand to the contact list for a specific contact; otherwise, the value will be Null

IMPORTANT: Event with 'reject' type will not have 'userId' in the webhook.
email The email address of the recipient

JavaScript API#

This basic integration uses a Javascript snippet, a block of code inserted into your website. It’s a low-impact way to send data to SmartSender — through your users’ web browsers. While an API integration is more flexible, this is a really quick way to get started.

Installation#

To install our JS API, you need to take the following steps:

  1. Generate and get JS code snippet
  2. Download and extract Worker File from the archive and add it to the root directory of your website.
  3. Include JS code snippet on every page in your app, immediately before the closing </body> tag.
  4. Properly identify your user.
  5. Call JS API methods to manage your user data.

IMPORTANT You should include this snippet on every page in your app, immediately before the closing </body> tag.

<script type="text/javascript" src="//js.smartsender.io/js/v1/61374132189.js">
</script>

INFO Here are some things to know before you begin using JS API.

We only track activity for users registered on your website after the js script is called.
We do not track anonymous or unregistered user activity.
To update an existing user’s variables, send the js script call again. You must include their identification and any new attribute values.
If the variables already exist in their profile, we’ll overwrite them.
If there are any new variables included in the call, we’ll add them to the profile.
We do not edit the user’s identification method if the contact already adds to the contact list.

User Identification#

To identify your user, you need to provide minimum one unique user identificator (userId | email | phoneNumber ).

<script type="text/javascript">
    var contact = new _smartSenderContact('user@example.com');
</script>

Add New Contact#

To add a contact to the Contact List you need properly identify your user and fire an event on your web page

IMPORTANT Add the following code to the main HTML template of your website before the closing tag </body>.

Required Initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/61374132189.js>
</script>
    <script type="text/javascript">
    var contact = new _smartSenderContact('{{identifier}}');
</script>

Required Call contact creation API method and add additional properties to your new contact in case of need.

<script type="text/javascript">
    contact.Add({
        active: true,
        name: "John Doe",
        firstName: "John",
        lastName: "Doe",
        email: "user@example.com",
        phoneNumber: "+15555555",
        userId: "myUserId",
        emailSubscribe: true,
        smsSubscribe: true,
        mobileWebPushSubscribe: true,
        desktopWebPushSubscribe: true,
        birthday: "1990-01-01",
        language: "en",
        gender: "male",
        timezone: "Europe/Tallinn",
        avatarLink: "http://img.smartsender.io/g/56fff0346b621206c38b4568/busines-man.png",
        facebookLink: "https://www.facebook.com/smartsender.io",
        instagramLink: "https://www.instagram.com/",
        twitterLink: "https://twitter.com/smart_sender",
        tiktokLink: "https://www.tiktok.com/",
        score: 100,
        sourceId: "5efc8503efeef96ca3151931",
        customerSourceId: "mySourceID",
        cac: {
            value:      2.55,
            currency:   "USD",
        },
        variables: [
            {name: "var1", value: "val1"},
            {name: "dateTimeVar", value: "2020-10-20"},
        ],
    });</script>

Update Contact Data#

To update contact data in the Contact List, you need to properly identify your user and fire an update event on your web page.

IMPORTANT Add the following code to the main HTML template of your website before the closing tag </body>.

'required' Identify your user.

<script type="text/javascript">
    var contact = new _smartSenderContact('{{identifier}}');
</script>

'optional' Add additional properties to your new contact in case of need.

<script type="text/javascript">
    var options = {
        firstName: '{{contactFirstName}}'
    };
</script>

'required' Call contact update API method.

<script type="text/javascript">
    contact.Add(options);
</script>

Fire Event#

To send a user event to SmartSender.io, you need to properly identify your user and fire an event on your web page.

IMPORTANT Add the following code to the main HTML template of your website before the closing tag </body>.

'required' Identify your user.

<script type="text/javascript">
    var contact = new _smartSenderContact('{{identifier}}');
</script>

'optional' Initialisation of event object. Params:

  1. 'required' YOUR_REGISTERED_EVENT_ID or EVENT_NAME of event registered in SmartSender.io.
  2. 'optional' Event Value: value in float or integer format correspondingly, dot divider.
  3. 'optional' Event Currency: Please use only EUR or USD. IMPORTANT Latin uppercase format. No numbers or other symbols allowed.
<script type="text/javascript">
    var event = new _smartSenderEvent('{{eventIdOrName}}', {{value}}, '{{USD}}');
</script>

'required' Call Fire Event API method.

<script type="text/javascript">
    contact.FireEvent(event);
</script>

Web Push Prompt#

To Call Web Push Notification One-click Subscription Prompt on your website, you need to properly identify your user and fire an event on your web page.

IMPORTANT Add the following code to the main HTML template of your website before the closing tag </body>.

'required' Identify your user.

<script type="text/javascript">
    var contact = new _smartSenderContact('{{identifier}}');
</script>

'required' Call “show web push subscription prompt” modal API method.

<script type="text/javascript">
    contact.ShowPushPrompt();
</script>

Telegram Link#

To generate Telegram bot one-click subscription link on your website, you need to properly identify your user and fire an event on your web page.

IMPORTANT Add the following code to the main HTML template of your website before the closing tag </body>.

'required' Identify your user.

<script type="text/javascript">
    var contact = new _smartSenderContact('{{identifier}}');
</script>

'required' Call “Generate telegram subscription link” API method.

<script type="text/javascript">
    contact.CreateTelegramSubscriptionLink('
        {{domElementId}}', 
        '{{telegramBotId}}'
    );
</script>

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