SmartSender API V3.0 | User Retention Automation

SmartSender API v3.0#

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

Get Account Info#

To get your Account information you need to send POST Request with your Access Token in headers to the following URL

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

IMPORTANT The body of the request is empty.

Response:

{
   "result":            true,
   "accountName":       "AccountName",
   "accountBalance":    100.00 
}

Return value
result	Indicated that the query was successful.
	true	The value indicates that the Account data was successfully fetched.
accountName	Your account name registered in the SmartSender system.
accountBalance	Current state of the account balance.

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and processed.
	false	The request is rejected.
Error description	“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/account/info';

/**
* 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, '');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Access-Token: $accessToken",
    'Content-Type: application/json',
    'Content-Length: ' . strlen(''),
]);

$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 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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": false,
    "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
	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. `IMPORTANT`That parameter is only available for Enterprise Plan. Request the parameter activation from the support team via support@smartsender.io.
	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). `IMPORTANT`Headers 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 string”
	“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 must be a string”
	“Argument subject must be a non-empty string”
	“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

IMPORTANT Do not send more than 10 concurrent API requests.

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. `IMPORTANT`That parameter is only available for Enterprise Plan. Request the parameter activation from the support team via support@smartsender.io.
	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.
result	true	Message was successfully sent out
messageId	The message unique identification number in SmartSender system. With this ID number you can get all the statistics on each sent message.

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The sending status of the message
	true	The message is accepted and queued
	false	The message is rejected
Error description	“Argument contactListId must be a non-empty string”
	“Argument contact must be a non-empty string”
	“Argument templateId must be a non-empty string”
	“Argument tags must be an array”
	“tag name must be a non-empty string”
	“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

IMPORTANT Do not send more than 10 concurrent API requests.

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
}

Return value You will get a list of successfully fetched messages and related events.
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!”
	“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/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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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 “From Name” linked to sending phone number that recipients will see on 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 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”
	“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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

Parameters
ids `'required'`	List of `messageId` 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/...

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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}”
	“Contact {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 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/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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

Parameters
ids `'required'`	List of `messageId` 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
}

Return Value
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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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 to your 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

IMPORTANT Do not send more than 10 concurrent API requests.

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 Telegram message status by Telegram message_id, you need to send POST Request to the following URL:

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
  "ids": [
    "YOUR_TELEGRAM_MESSAGE_ID_1",
    "YOUR_TELEGRAM_MESSAGE_ID_2", 
    "YOUR_TELEGRAM_MESSAGE_ID_3"
  ]
}

Parameters
ids `'required'`	List of `messageId` 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

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

Response:

{
    "result": true
}

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

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors
	“name of variable must be a string”
	“name of variable can not be empty”
	“variable \”{name}\” is reserved and can not be added as custom variable”
	“invalid name of variable {name}”
	“Invalid authorization token!”
	“Internal 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/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

IMPORTANT Do not send more than 10 concurrent API requests.

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

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”
	“no global variables found”
	“no matches found for global variable {globalVariable}”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data found for key {userId}”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

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

$body = json_encode([
    'name' => 'globalVariable',  //Send empty array 
]);                              //to get 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

IMPORTANT Do not send more than 10 concurrent API requests.

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 Contacts#

To add | update | delete | get 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    "contactListId": "YOUR_CONTACT_LIST_ID",
    "webHookUri": "YOUR_WEBHOOK_URL",
    "contacts": [
        {
            "name": "John Doe",
            "email": "user@example.com",
            "phoneNumber": "+15555555",
            "userId": "myUserId",
            "active": true,
            "emailSubscribe": true,
            "smsSubscribe": true,
            "desktopWebPushSubscribe": true,
            "mobileWebPushSubscribe": true,
            "firstName": "John",
            "lastName": "Doe",
            "contactBirthday": "1990-01-01",
            "contactLanguage": "en",
            "contactGender ": 2,
            "contactTimezone": "Europe/Tallinn",
            "contactScore": 100,
            "avatarLink": "img.smartsender.io/g/56fff04568.jpg",
            "facebookLink": "facebook.com/smartsender.io",
            "instagramLink": "instagram.com/smartsender",
            "linkedInLink": "linkedin.com/company/smartsender",
            "twitterLink": "twitter.com/smart_sender",
            "tiktokLink": "tiktok.com/smartsender",
            "sourceId": "Source_ID_from_SmartSender",
            "customerSourceId": "Customer_Source_ID_From_Your_Platform",
            "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. `IMPORTANT`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
	name `'optional'`	The optional display name to use for the recipient
	email `'optional'`	Contact’s email address.
	phoneNumber `'optional'`	`IMPORTANT:` should be `valid E.164 phone number` format.
	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
	firstName ‘optional’	Contact’s first name
	lastName ‘optional’	Contact’s last name
	contactBirthday ‘optional’	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
	contactLanguage ‘optional’	Contact’s locale in `ISO 639-1` format
	contactGender ‘optional’	Contact’s gender in `ISO/IEC 5218` format
		0	Not known
		1	Male
		2	Female
		9	Not applicable
	contactTimezone ‘optional’	Contact’s timezone in `ISO 8601` format
	contactScore ‘optional’	Contact Score
	avatarLink ‘optional’	Link to contact’s avatar image.
	facebookLink ‘optional’	Link to contact’s Facebook profile.
	instagramLink ‘optional’	Link to contact’s Instagram profile.
	linkedInLink ‘optional’	Link to contact’s LinkedIn profile.
	twitterLink ‘optional’	Link to contact’s Twitter profile.
	tiktokLink ‘optional’	Link to contact’s TikTok profile.
	variables ‘optional’	An array of contact variables and their values.
		name `'required'`	Variable name in lowerCamelCase format `IMPORTANT` 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 have higher priority.
	cac ‘optional’	value `'required'`	CAC value in `'ENUM_STRING'` format correspondingly
		currency `'required'`	(EUR, USD) `IMPORTANT` 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 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 desktopWebPushSubscribe can be true or false”
	“Argument mobileWebPushSubscribe 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 userId must be filled at contact position {i}”
	“Argument {argument} required”
	“Argument firstName must be a string”
	“Argument firstName must be a string with max length within 255 characters”
	“Argument lastName mustbe a string”
	“Argument lastName must be a string with max length within 255 characters”
	“Argument birthday must be a YYYY-MM-DD date”
	“Argument language must be a valid ISO language”
	“Unknown gender value”
	“Argument timezone must be a valid timezone string”
	“Argument score must have a numeric value”
	“Argument avatarLink must be a valid URL”
	“Argument facebookLink must be a valid URL”
	“Argument instagramLink must be a valid URL”
	“Argument linkedInLink must be a valid URL”
	“Argument twitterLink must be a valid URL”
	“Argument tiktokLink must be a valid URL”
	“Argument sourceId must be a string”
	“sourceId {sourceId} not found in your account at contact position {i}”
	“Argument customerSourceId must be an alphanumeric string with max length within 40 characters”
	“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”
	“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 failed for key\/secret $key \/$accessToken”

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.

Request body

{
    "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"
            }
        ]
    }
}

Parameters
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"           => "John Doe",
            "email"          => "user@example.com",
            "phoneNumber"    => "+15555555",
            "userId"         => "myUserId",
            "active"         => true,
            "emailSubscribe" => true,
            "smsSubscribe"   => true,
            "desktopWebPushSubscribe"=> true, 
            "mobileWebPushSubscribe"=> true, 
            "firstName"      => "John", 
            "lastName"       => "Doe", 
            "contactBirthday"=> "1990-01-01", 
            "contactLanguage"=> "en", 
            "contactGender " => 2, 
            "contactTimezone"=> "Europe/Tallinn", 
            "contactScore"   => 100, 
            "avatarLink"     => "img.smartsender.io/g/56fff04568.jpg", 
            "facebookLink"   => "facebook.com/smartsender.io", 
            "instagramLink"  => "instagram.com/smartsender", 
            "linkedInLink"   => "linkedin.com/company/smartsender", 
            "twitterLink"    => "twitter.com/smart_sender", 
            "tiktokLink"     => "tiktok.com/smartsender", 
            "sourceId"       => "5efc8503efeef96ca3151931", 
            "customerSourceId"=> "mySourceID",
            "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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
  "contactListId": "YOUR_CONTACT_LIST_ID",
  "webHookUri": "YOUR_WEBHOOK_URL",
  "upsert": false,
  "contacts": [
    {
      "contact": "+15555555",      
      "name": "John Doe",
      "email": "user@example.com",
      "phoneNumber": "+15555555",
      "userId": "myUserId",
      "active": true,
      "emailSubscribe": true,
      "smsSubscribe": true,
      "desktopWebPushSubscribe": true,
      "mobileWebPushSubscribe": true,
      "telegramSubscribe": true,
      "firstName": "John",
      "lastName": "Doe",
      "contactBirthday": "1990-01-01",
      "contactLanguage": "en",
      "contactGender ": 2,
      "contactTimezone": "Europe/Tallinn",
      "contactScore": 100,
      "avatarLink": "img.smartsender.io/g/06c38b4568.jpg",
      "facebookLink": "facebook.com/smartsender.io",
      "instagramLink": "instagram.com/smartsender",
      "linkedInLink": "linkedin.com/company/smartsender",
      "twitterLink": "twitter.com/smart_sender",
      "tiktokLink": "tiktok.com/smartsender",
      "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. `IMPORTANT`You can update only `100` contacts at once. `IMPORTANT`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
	contact `'required'`	The unique user identificator (`userId` \| `email` \| `phoneNumber`) of the contact you want to update
	name `'optional'`	The optional display name to use for the recipient
	email `'optional'`	Contact’s email address.
	phoneNumber `'optional'`	`IMPORTANT` should be `valid E.164 phone number` format.
	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 desktop web push notifications 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 mobile web push notifications or not. The default value is false (unsubscribed).
		true ‘optional’	Subscribe contact to mobile webpush notifications
		false `'default'`	Unsubscribe contact from mobile webpush notification
	telegramSubscribe ‘optional’	You can set if the contact is subscribed to receiving Telegram messages or not. The default value is false (unsubscribed).
		true ‘optional’	Subscribe contact to Telegram messages
		false `'default'`	Unsubscribe contact from Telegram messages
	firstName ‘optional’	Contact’s first name
	lastName ‘optional’	Contact’s last name
	contactBirthday ‘optional’	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
	contactLanguage ‘optional’	Contact’s locale in `ISO 639-1` format
	contactGender ‘optional’	Contact’s gender in `ISO/IEC 5218` format
		0	Not known
		1	Male
		2	Female
		9	Not applicable
	contactTimezone ‘optional’	Contact’s timezone in `ISO 8601` format
	contactScore ‘optional’	Contact Score
	avatarLink ‘optional’	Link to contact’s avatar image.
	facebookLink ‘optional’	Link to contact’s Facebook profile.
	instagramLink ‘optional’	Link to contact’s Instagram profile.
	linkedInLink ‘optional’	Link to contact’s LinkedIn profile.
	twitterLink ‘optional’	Link to contact’s Twitter profile.
	tiktokLink ‘optional’	Link to contact’s TikTok profile.
	variables ‘optional’	An array of contact variables and their values.
		name `'required'`	Variable name in lowerCamelCase format `IMPORTANT` 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 have higher priority.
	cac ‘optional’	value `'required'`	CAC value in `'ENUM_STRING'` format correspondingly
		currency `'required'`	(EUR, USD) `IMPORTANT` 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 desktopWebPushSubscribe can be true or false”
	“Argument mobileWebPushSubscribe can be true or false”
	“Argument firstName must be a string”,
	“Argument firstName must be a string with max length within 255 characters”
	“Argument lastName must be a string”,
	“Argument lastName must be a string with max length within 255 characters”
	Argument birthday must be a YYYY-MM-DD date”
	“Argument language must be a valid ISO language”
	“Unknown gender value”
	“Argument timezone must be a valid timezone string”
	“Argument score must have a numeric value”
	“Argument avatarLink must be a valid URL”
	“Argument facebookLink must be a valid URL”
	“Argument instagramLink must be a valid URL”
	“Argument linkedInLink must be a valid URL”
	“Argument twitterLink must be a valid URL”
	“Argument tiktokLink must be a valid URL”
	“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 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 customerSourceId must be a string”
	“Argument customerSourceId must be an alphanumeric string with max length within 40 characters”
	“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.

Request body

{
    "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"
            }
        ]
    }
}

Parameters
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"           => "John Doe",
            "email"          => "user@example.com",
            "phoneNumber"    => "+15555555",
            "userId"         => "myUserId",
            "active"         => true,
            "emailSubscribe" => true,
            "smsSubscribe"   => true,
            "desktopWebPushSubscribe"=> true, 
            "mobileWebPushSubscribe"=> true, 
            "firstName"      => "John", 
            "lastName"       => "Doe", 
            "contactBirthday"=> "1990-01-01", 
            "contactLanguage"=> "en", 
            "contactGender " => 2, 
            "contactTimezone"=> "Europe/Tallinn", 
            "contactScore"   => 100, 
            "avatarLink"     => "img.smartsender.io/g/06c38b4568.jpg", 
            "facebookLink"   => "facebook.com/smartsender.io", 
            "instagramLink"  => "instagram.com/smartsender", 
            "linkedInLink"   => "linkedin.com/company/smartsender", 
            "twitterLink"    => "twitter.com/smart_sender", 
            "tiktokLink"     => "tiktok.com/smartsender", 
            "sourceId"       => "5efc8503efeef96ca3151931", 
            "customerSourceId"=> "mySourceID",
            "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);

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

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

Response:

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

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

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and queued. The result will be sent via webhook to provided link.
	false	The request is rejected
requestId	Unique request ID to be used to match the specific “Remove contact” request with the Status Webhook which will be sent by SmartSender after the request was processed.
Error description	“Maximum count of records per transaction is 100, current {n}”
	“Argument contactListId must be a non-empty string”
	“Argument webHookUri must be a valid URI”
	“Argument emails must be a list of emails”
	“Each email must be a string”
	“Argument phoneNumbers must be a list of phoneNumbers”
	“Each phoneNumber must be a string”
	“Argument userIds 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.

Request body

{
    "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"
            }
        ]
    }
}

Parameters
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	“Success” 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}”
		“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 userIds 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”

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

IMPORTANT Do not send more than 10 concurrent API requests.

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 request successfully processed
			fail	The request failed
		webHookUri	Webhook URL included in the request 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 successful 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 userId 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 userId 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 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/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);

Get Contact#

To get a contact 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/contact/get

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
 "contactListId": "YOUR_CONTACT_LIST_ID",
 "email":         "user@example.com",
 "phoneNumber":   "+15555555",
 "userId":        "myUserId"
}

Parameters
contactListId `'required'`	ID of the Contact List where the contact to be fetched belongs. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
`IMPORTANT`Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber` ) is required.
email `'optional'`	Contact’s email address.
phoneNumber `'optional'`	`IMPORTANT:` should be `valid E.164 phone number` format.
userId `'optional'`	Contact’s unique user ID from your platform to enable management of the contact in the list based on it.

Response:

{
    "result":               true,
    "contact": {
        "name":             "John Doe",
        "email":            "user@example.com",
        "phoneNumber":      "+15555555",
        "userId":           "myUserId",
        "active":           true,
        "emailSubscribe":           true,
        "smsSubscribe":             true,
        "desktopWebPushSubscribe":  false,
        "mobileWebPushSubscribe":   false,
        "telegramSubscribe":        false,
        "createdAt":        "2021-12-24 13:32:53",
        "updatedAt":        "2021-12-30 11:48:05",
        "avatarLink":       "img.smartsender.io/g/56fff04568.jpg",
        "contactBirthday":  1990-01-01,
        "contactLanguage":  "en",
        "firstName":        "John",
        "lastName":         "Doe",
        "contactGender":    "0",
        "contactTimezone":  "Europe/Tallinn",
        "facebookLink":     "facebook.com/smartsender.io",
        "instagramLink":    "instagram.com/smartsender",
        "linkedInLink":     "linkedin.com/company/smartsender",
        "twitterLink":      "twitter.com/smart_sender",
        "tiktokLink":       "tiktok.com/smartsender",
        "contactScore":     "0",
        "sourceName":       "Google",
        "sourceId":           "Source_ID_from_SmartSender",
        "customerSourceId": "хххххх",
        "variables": [
            {
                "name":      "var1",
                "value":     null
            }
        ],
        "cac": {
            "value":                "0.30000",
            "currency":             "USD"
        }
    },
    "errors": []
}

Return value
result	The value indicates that the contact was successfully fetched from your Contact List.
	true	Contact was successfully fetched.
contact `'required'`	An array of contact information.
	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` format.
	userId `'optional'`	Contact’s unique user ID from your platform to enable management of the contact in the list based on it.
	active `'optional'`	Indicates if the contact is enable Contact List or not.
		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’	Indicates if the contact is subscribed to receiving Emails or not.
		true ‘optional’	Contact is subscribed to Emails.
		false `'default'`	Unsubscribe contact from Emails.
	smsSubscribe ‘optional’	Indicates if the contact is subscribed to receiving SMS or not.
		true ‘optional’	Contact is subscribed to SMS.
		false `'default'`	Contact is ubsubscribed from SMS.
	desktopWebPushSubscribe ‘optional’	Indicates if the contact is subscribed to receiving Desktop Web Push notifications or not.
		true ‘optional’	Contact is subscribed to Desktop Web Push notifications.
		false `'default'`	Contact is ubsubscribed from Desktop Web Push notifications.
	mobileWebPushSubscribe ‘optional’	Indicates if the contact is subscribed to receiving Mobile Web Push notifications or not.
		true ‘optional’	Contact is subscribed to Mobile Web Push notifications.
		false `'default'`	Contact is ubsubscribed from Mobile Web Push notifications.
	telegramSubscribe ‘optional’	Indicates if the contact is subscribed to receiving Telegram messages or not.
		true ‘optional’	Subscribe contact to Telegram messages.
		false `'default'`	Contact is ubsubscribed from Telegram messages.
	firstName ‘optional’	Contact’s first name.
	lastName ‘optional’	Contact’s last name.
	contactBirthday ‘optional’	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
	contactLanguage ‘optional’	Contact’s locale in `ISO 639-1` format
	contactGender ‘optional’	Contact’s gender in `ISO/IEC 5218` format
		0	Not known
		1	Male
		2	Female
		9	Not applicable
	contactTimezone ‘optional’	Contact’s timezone in `ISO 8601` format
	contactScore ‘optional’	Contact Score.
	avatarLink ‘optional’	Link to contact’s avatar image.
	facebookLink ‘optional’	Link to contact’s Facebook profile.
	instagramLink ‘optional’	Link to contact’s Instagram profile.
	linkedInLink ‘optional’	Link to contact’s LinkedIn profile.
	twitterLink ‘optional’	Link to contact’s Twitter profile.
	tiktokLink ‘optional’	Link to contact’s TikTok profile.
	variables ‘optional’	An array of contact variables and their values.
		name `'required'`	Variable name in lowerCamelCase format.
		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) `IMPORTANT` Please use only latin uppercase format. No numbers or other symbols allowed.

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and processed.
	false	The request is rejected.
Error description	“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”
	“Argument ‘contactListId’ must be a non-empty 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”

PHP Example

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

$body = json_encode([
    "contactListId" => "YOUR_CONTACT_LIST_ID",
    "email"         => "user@example.com",
    "phoneNumber"   => "+15555555",
    "userId"        => "myUserId",
]);

/**
* 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

}

Parameters
email `'optional'`	Email address. RFC validity not required.
rejectType `'optional'`	Used to indicate that address is invalid or non existing. `WARNING:` Minimum one rejectType (`hard` \| `complaint` \| `list-unsubscribe` ) is required.
	hard	Used to indicate that address is invalid or non existing.
	complaint	Used to indicate that user complaint or asked to unsubscribe.
	list-unsubscribe	Used to indicate that user unsubscribed by list-unsubscribed mechanism.
withRawLog `'optional'`	Get the reason, why ESP hard bounced your contact. It is raw information that we receive from the target ESP.`IMPORTANT` That parameter is only available for Enterprise Plan. Request the parameter activation from the support team via support@smartsender.io.
	true `'optional'`	All data from the Email Black List Raw Log will be displayed.
	false `'default'`	No data from the Email Black List Raw Log will be displayed.
offset `'optional'`	Integer shift. `Default value`: 0
limit `'optional'`	Integer limit. `Default value`: 20

Response:

{
     "result":true,
     "data":[
      {
       "email":"user@example.com",
       "type":"hard",
       "rawLog": "Sample error text",
       "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
	rawLog `'optional'`	The reason, why ESP hard bounced your contact. It is raw information that we receive from the target ESP. `IMPORTANT` That parameter is only available for Enterprise Plan. Request the parameter activation from the support team via support@smartsender.io.
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 numeric 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",
        "withRawLog" => false,
        "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

IMPORTANT Do not send more than 10 concurrent API requests.

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 {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 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 Contact List#

To get Contact List data from your account you need to send POST Request with your Access Token in headers to the following URL

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

Below you can see the table with required parameters.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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 variable was successfully added.
	true	Variable 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);

Get Contact List#

To get the Contact List details from the account you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/contact-list/get

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    "domainId":     "YOUR_DOMAIN_ID",
    "domain":       "Default Contact List",
    "contactListId":"YOUR_CONTACT_LIST_ID"
}

Parameters
`IMPORTANT` Minimum one identification (`domainId` \| `domain` \| `contactListId`) is required.
domainId `optional`	Unique domain ID in SmartSender system. `IMPORTANT` `default` Contact List data will be returned.
domain `optional`	The verified domain name from your SmartSender account.
contactListId `optional`	The ID of the Contact List.

Response:

{
    "result": true,
    "data": {
        "contactListName": "Default Contact List",
        "contactListId":    "YOUR_CONTACT_LIST_ID",
        "domainId":         "YOUR_DOMAIN_ID",
        "domain":           "senderDomain.com",
        "defaultFromEmail": "notify@senderDomain.com",
        "defaultFromName":  "notify@senderDomain.com",
        "company":          "SmartSender",
        "replyToEmail":     "support@senderDomain.com",
        "replyToName":      "Support Team",
        "smsFromName":      "SmartSender",
        "isDefault":        "1",
        "createdAt":        "2020-10-02 12:44:03",
        "updatedAt":        "2020-10-02 12:44:03",
        "customVariables": [
            {
                "name": "companyName",
                "type": "string"
            }
        ],
        "defaultVariables": [
            {
                "name": "createdAt",
                "type": "datetime"
            },
            {
                "name": "email",
                "type": "string"
            },
            {
                "name": "userId",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string"
            },
            {
                "name": "active",
                "type": "bool"
            },
            {
                "name": "phoneNumber",
                "type": "string"
            },
            {
                "name": "emailSubscribe",
                "type": "bool"
            },
            {
                "name": "smsSubscribe",
                "type": "bool"
            },
            {
                "name": "desktopWebPushSubscribe",
                "type": "bool"
            },
            {
                "name": "mobileWebPushSubscribe",
                "type": "bool"
            },
            {
                "name": "telegramSubscribe",
                "type": "bool"
            },
            {
                "name": "customerSourceId",
                "type": "string"
            },
            {
                "name": "sourceName",
                "type": "string"
            },
            {
                "name": "sourceId",
                "type": "string"
            },
            {
                "name": "avatarLink",
                "type": "string"
            },
            {
                "name": "contactBirthday",
                "type": "date"
            },
            {
                "name": "contactLanguage",
                "type": "string"
            },
            {
                "name": "firstName",
                "type": "string"
            },
            {
                "name": "lastName",
                "type": "string"
            },
            {
                "name": "contactGender",
                "type": "string"
            },
            {
                "name": "contactTimezone",
                "type": "string"
            },
            {
                "name": "facebookLink",
                "type": "string"
            },
            {
                "name": "instagramLink",
                "type": "string"
            },
            {
                "name": "linkedInLink",
                "type": "string"
            },
            {
                "name": "twitterLink",
                "type": "string"
            },
            {
                "name": "tiktokLink",
                "type": "string"
            },
            {
                "name": "contactScore",
                "type": "string"
            },
            {
                "name": "cac",
                "type": "array"
            }
        ]
    },
    "errors": []
}

Return value
result	Indicated that the query was successful.
result	true	The value indicates that the Contact List data was successfully fetched from your account.
data	An array of fetched information.
	contactListName	Name of the Contact List. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
	contactListId	ID of the Contact List. The list should be already created in your account on Lists page: `https://partner.smartsender.io/email-list/`
	domainId	Unique domain ID in SmartSender system.
	domain	Verified domain name from your SmartSender account. `IMPORTANT` `default` Contact List data will be returned.
	defaultFromEmail	`default` From_Email address of the Contact List.
	defaultFromName	`default` From_Name of the Contact List.
	company	The official name of your company including incorporation type used for the footer information.
	replyToEmail	`default` Reply-to-Email of the Contact List.
	replyToName	`default` Reply-to-Name of the Contact List.
	smsFromName	`default` SMS From-Name of the Contact List.
	isDefault	Indicates that the Contact List is `default` for the domain.
		true	Indicates that the Contact List is not `default` for the domain.
		false
	createdAt	Contact List creation time in `YYYY-MM-DD h:i:s format`
	updatedAt	Contact List last updating time in `YYYY-MM-DD h:i:s format`
	customVariables	An array of customer variables from the Contact List.
		name	Specific custom variables created from the Contact List.
		type	Type of the specific variable fetched from the Contact List.
	defaultVariables	Default system variables from the Contact List. `string` \| `date` \| `datetime` \| `bool` \| `array`
		createdAt `date`	Contact List creation UTC DateTime.
		email `string`	Contact’s email address.
		userId `string`	Contact’s unique user ID from your platform that enables management of the contact in the list based on it.
		name `string`	The optional display name to use for the recipient.
		active `bool`	Indicates if the contact is enable Contact List or not.
		phoneNumber `string`	Contact’s phone number. `IMPORTANT` should be a valid `E.164 phone number` format.
		emailSubscribe `bool`	Indicates if the contact is subscribed to receiving Emails or not.
		smsSubscribe `bool`	Indicates if the contact is subscribed to receiving SMS or not.
		desktopWebPushSubscribe `bool`	Indicates if the contact is subscribed to receiving Desktop Web Push notifications or not.
		mobileWebPushSubscribe `bool`	Indicates if the contact is subscribed to receiving Mobile Web Push notifications or not.
		telegramSubscribe `bool`	Indicates if the contact is subscribed to receiving Telegram messages or not.
		customerSourceId `string`	Contact’s unique source ID from your system to synchronize two sides.
		sourceName `string`	Name of your contact acquisition source.
		sourceId `string`	Contact’s unique source ID from SmartSender platform.
		avatarLink `string`	Link to contact’s avatar image.
		contactBirthday `date`	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
		contactLanguage `string`	Contact’s locale in `ISO 639-1 format`
		firstName `string`	Contact’s first name.
		lastName `string`	Contact’s last name.
		contactGender `string`	Contact’s gender in `ISO/IEC 5218` format
		contactTimezone `string`	Contact’s timezone in `ISO 8601` format
		facebookLink `string`	Link to contact’s Facebook profile.
		instagramLink `string`	Link to contact’s Instagram profile.
		linkedInLink `string`	Link to contact’s LinkedIn profile.
		twitterLink `string`	Link to contact’s Twitter profile.
		tiktokLink `string`	Link to contact’s TikTok profile.
		contactScore `string`	Contact Score.
		cac `array`	Contact’s customer acquisition cost.

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and processed.
	false	The request is rejected.
Error description	“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”
	“Contact lists not found in your domain”
	“Domain not found in your account”
	“Minimum one identification (domainId \| domain \| contactListId) is required.”
	“Argument ‘domainId’ must be a non-empty string”
	“Argument ‘domain’ must be a non-empty string”
	“Argument ‘contactListId’ must be a non-empty string”

PHP Example

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

$body = json_encode([
   "domainId"      => "YOUR_DOMAIN_ID",
   "domain"        => "YOUR_DOMAIN_NAME",
   "contactListId" => "YOUR_CONTACT_LIST_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);

Find Contact List#

To find your Contact Lists’ details from the account you need to send POST Request with your Access Token in headers to the following URL

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    "domainId":         "YOUR_DOMAIN_ID",
    "domain":           "senderDomain.com",
    "contactListId":    "YOUR_CONTACT_LIST_ID",
    "contactListName":  "Default Contact List",
    "offset":           0,
    "limit":            20
}

Parameters
domainId `optional`	Unique domainId that is already registered in SmartSender system.
domain `optional`	Unique DomainName that is already registered in SmartSender system.
contactListId `optional`	ID of the Contact List where the contact to be updated belongs. The list should be already created in your account on the Lists page: `https://partner.smartsender.io/email-list/`
contactListName `optional`	Name of the Contact List. The list should be already created in your account on the Lists page: https://partner.smartsender.io/email-list/
offset `optional`	Allows you to omit a specified number of rows (number of domains) before the beginning of return rows (events) from the query. The `default` is 0.
limit `optional`	Allows you to limit the number of rows (domains) returned from a query. The `default` is 20.

Response:

{
    "result": true,
    "data": [
    {
        "contactListName":  "Default Contact List",
        "contactListId":    "YOUR_FIRST_CONTACT_LIST_ID",
        "domainId":         "YOUR_DOMAIN_ID",
        "domain":           "senderDomain.com",
        "defaultFromEmail": "notify@senderDomain.com",
        "defaultFromName":  "notify@senderDomain.com",
        "company":          "SmartSender",
        "replyToEmail":     "support@senderDomain.com",
        "replyToName":      "Support Team",
        "smsFromName":      "SmartSender",
        "isDefault":        "1",
        "createdAt":        "2020-10-02 12:44:03",
        "updatedAt":        "2020-10-02 12:44:03",
        "customVariables": [
            {
                "name": "companyName",
                "type": "string"
            }
        ],
        "defaultVariables": [
            {
                "name": "createdAt",
                "type": "datetime"
            },
            {
                "name": "email",
                "type": "string"
            },
            {
                "name": "userId",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string"
            },
            {
                "name": "active",
                "type": "bool"
            },
            {
                "name": "phoneNumber",
                "type": "string"
            },
            {
                "name": "emailSubscribe",
                "type": "bool"
            },
            {
                "name": "smsSubscribe",
                "type": "bool"
            },
            {
                "name": "desktopWebPushSubscribe",
                "type": "bool"
            },
            {
                "name": "mobileWebPushSubscribe",
                "type": "bool"
            },
            {
                "name": "telegramSubscribe",
                "type": "bool"
            },
            {
                "name": "customerSourceId",
                "type": "string"
            },
            {
                "name": "sourceName",
                "type": "string"
            },
            {
                "name": "sourceId",
                "type": "string"
            },
            {
                "name": "avatarLink",
                "type": "string"
            },
            {
                "name": "contactBirthday",
                "type": "date"
            },
            {
                "name": "contactLanguage",
                "type": "string"
            },
            {
                "name": "firstName",
                "type": "string"
            },
            {
                "name": "lastName",
                "type": "string"
            },
            {
                "name": "contactGender",
                "type": "string"
            },
            {
                "name": "contactTimezone",
                "type": "string"
            },
            {
                "name": "facebookLink",
                "type": "string"
            },
            {
                "name": "instagramLink",
                "type": "string"
            },
            {
                "name": "linkedInLink",
                "type": "string"
            },
            {
                "name": "twitterLink",
                "type": "string"
            },
            {
                "name": "tiktokLink",
                "type": "string"
            },
            {
                "name": "contactScore",
                "type": "string"
            },
            {
                "name": "cac",
                "type": "array"
            }
        ]
    },
    {
       "contactListId":    "YOUR_SECOND_CONTACT_LIST_ID",
       .... 
    }
  ],
    "totalCount": 18,
    "offset": 0,
    "limit": 20,
    "errors": []
}

Return value
result	Indicated that the query was successful.
result	true	The value indicates that the Contact List data was successfully fetched from your account.
data	An array of fetched information.
	contactListName	Name of the Contact List. The list should be already created in your account on the Lists page: `https://partner.smartsender.io/email-list/`
	contactListId	ID of the contact list. The list should be already created in your account on the Lists page: `https://partner.smartsender.io/email-list/`
	domainId	Unique domain ID in SmartSender system.
	domain	Verified domain name from your SmartSender account. `IMPORTANT` `default` Contact List data will be returned.
	defaultFromEmail	`default` From_Email address of the Contact List.
	defaultFromName	`default` From_Name of the Contact List.
	company	The official name of your company including incorporation type used for the footer information.
	replyToEmail	`default` Reply-to-Email of the Contact List.
	replyToName	`default` Reply-to-Name of the Contact List.
	smsFromName	`default` SMS From-Name of the Contact List.
	isDefault	Indicates if the Contact List is the default for the domain name or not.
		true	Indicates that the Contact List is `default` for the particular domain.
		false	Indicates that the Contact List is not `default` for the particular domain
	createdAt	Contact List creation time in `YYYY-MM-DD h:i:s format`
	updatedAt	Contact List last updating time in `YYYY-MM-DD h:i:s format`
	customVariables	An array of customer variables from Contact List.
		name	Specific custom variables created from the Contact List.
		type	Type of the specific variable fetched from the Contact List.
	defaultVariables	Default system variables from the Contact List. `string` \| `date` \| `datetime` \| `bool` \| `array`
		createdAt `date`	Contact List creation UTC DateTime.
		email `string`	Contact’s email address.
		userId `string`	Contact’s unique user ID from your platform that enables management of the contact in the list based on it.
		name `string`	The optional display name to use for the recipient.
		active `bool`	Indicates if the contact is enable Contact List or not.
		phoneNumber `string`	Contact’s phone number. `IMPORTANT` should be a valid `E.164 phone number` format.
		emailSubscribe `bool`	Indicates if the contact is subscribed to receiving Emails or not.
		smsSubscribe `bool`	Indicates if the contact is subscribed to receiving SMS or not.
		desktopWebPushSubscribe `bool`	Indicates if the contact is subscribed to receiving Desktop Web Push notifications or not.
		mobileWebPushSubscribe `bool`	Indicates if the contact is subscribed to receiving Mobile Web Push notifications or not.
		telegramSubscribe `bool`	Indicates if the contact is subscribed to receiving Telegram messages or not.
		customerSourceId `string`	Contact’s unique source ID from your system to synchronize two sides.
		sourceName `string`	Name of your contact acquisition source.
		sourceId `string`	Contact’s unique source ID from SmartSender platform.
		avatarLink `string`	Link to contact’s avatar image.
		contactBirthday `date`	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
		contactLanguage `string`	Contact’s locale in `ISO 639-1 format`
		firstName `string`	Contact’s first name.
		lastName `string`	Contact’s last name.
		contactGender `string`	Contact’s gender in `ISO/IEC 5218` format
		contactTimezone `string`	Contact’s timezone in `ISO 8601` format
		facebookLink `string`	Link to contact’s Facebook profile.
		instagramLink `string`	Link to contact’s Instagram profile.
		linkedInLink `string`	Link to contact’s LinkedIn profile.
		twitterLink `string`	Link to contact’s Twitter profile.
		tiktokLink `string`	Link to contact’s TikTok profile.
		contactScore `string`	Contact Score.
		cac `array`	Contact’s customer acquisition cost.
	totalCount	Total number of fetched Contact Lists.
	offset	Allows you to omit a specified number of rows (number of templates) before the beginning of return rows (templates) from the query. The `default` is ’20’
	limit	Allows you to limit the number of rows (Contact Lists) returned from a query. The `default` is ‘0’.

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The rejection acceptance status.
	true	The request is accepted and processed.
	false	The request is rejected
Error description	“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”
	“Parameter ‘limit’ must have a numeric value”
	“Parameter ‘offset’ must have a numeric value”
	“Argument ‘contactListName’ must be a non-empty string”
	“Argument ‘contactListId’ must be a non-empty string”
	“Argument ‘domain’ must be a non-empty string”
	“Argument ‘domainId’ must be a non-empty string”

PHP Example

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

$body = json_encode([
   "domainId"        => "YOUR_DOMAIN_ID",
   "domain"          => "senderDomain.com",
   "contactListId"   => "YOUR_CONTACT_LIST_ID",
   "contactListName" => "Default Contact List",
   "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 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

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

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

Response:

{
   "result":true
}

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

Example Error Response JSON

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

Errors. The reason for the rejection.
result	The status of the request.
	true	The request is accepted and queued
	false	The request is rejected
errors	“Maximum count of records per transaction is 100, current {n}”
	“{phoneNumber} is not a valid E.164 phone number”
	“Allowed reject types are {allowed}, but {rejectType} given”
	“Invalid authorization token!”
	“Internal server error”
	“Bad Request”
	“no matches found for access token {accessToken}”
	“user {id} not enabled”
	“no data 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/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

IMPORTANT Do not send more than 10 concurrent API requests.

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 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/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

IMPORTANT Do not send more than 10 concurrent API requests.

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”
	“Argument {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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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
CAC ‘optional’	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

IMPORTANT Do not send more than 10 concurrent API requests.

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
cac ‘optional’	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

IMPORTANT Do not send more than 10 concurrent API requests.

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

PHP Example:

$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);

Get source#

To get the contact acquisition source details from account you need to send POST Request with your Access Token in headers to the following URL

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
  "name": "SourceName",
  "customerSourceId": "mySourceID",
  "sourceId" : "sourceId"
}

Parameters
name `'optional'`	Unique contact acquisition source name that is already registered in the system.
customerSourceId `'optional'`	Unique customerSourceId that is already registered in the system. `INFO` Works as an alias for sourceId.
sourceId `'optional'`	Unique contact acquisition source that is already registered in the system.

Response:

{
  "result": true,
  "data": {
    "sourceId": "SourceId",
    "name": "SourceName",
    "customerSourceId": "mySourceID",
    "cac": {
      "value": "5.00",
      "currency": "EUR"
    },
    "createdAt": "2021-07-14 15:50:18",
    "updatedAt": "2021-07-14 15:50:18"
  }
}

Return value
result	The value indicates that the source was successfully fetched from your account.
	true	The source was successfully fetched.
data	sourceId	Unique contact acquisition source that is already registered in the system.
	name	sourceName n the SmartSender system.
	customerSourceId	Unique customerSourceId that is already registered in the system. `INFO` Works as an alias for sourceId.
	cac	value	Contact acquisition cost in `'ENUM_STRING'` format correspondingly.
		currency	(EUR, USD) `WARNING` Please use only latin uppercase format. No numbers or other symbols allowed.
	createdAt	Source creation time in YYYY-MM-DD h:i:s format
	updatedAt	Last time when the information of the source was updated in YYYY-MM-DD h:i:s format

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 ‘sourceId’ must be a non-empty alphanumeric string”
	“Argument ‘name’ must be a non-empty alphanumeric string with a max length of 40 chars”
	“Argument’customerSourceId’ must be an alphanumeric string with max length 40 chars”
	“Minimum one unique contact source identification ( sourceId \| customerSourceId \| name ) is required.”
	“No records found by these 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/get';
$body = json_encode([
   "name" => "SourceName",
   "customerSourceId" => "YOUR_customerSourceId",
   "sourceId" => "SourceName"
/** * 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.

IMPORTANT Do not send more than 10 concurrent API requests.

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

Fire 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/fire

IMPORTANT Do not send more than 10 concurrent API requests.

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"
          },
  "variables": [
    {
       "name": "newVariableName1",
       "value": "newVariableValue1"
    },
    {
       "name": "newVariableName2",
       "value": "YYYY-MM-DD"
    }
 ]
}

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. IP address 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.
variables ‘optional’	You can add an associative array of custom variables which will be placed in your template which we host. `IMPORTANT` Variables will be available only in Workflows. Please, take in account variables usage priorities is case of conflicting variables: `First Priority`: Variable from API request; `Second Priority`: Variable from the Component Custom Variables; `Third Priority`: Variable from the contact list.

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

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	An array of fetched information.
	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”
	“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);

Get event#

To get the custom event details from account you need to send POST Request with your Access Token in headers to the following URL

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    "id": "YOUR_REGISTERED_EVENT_ID",
    "name": "YOUR_REGISTERED_EVENT_NAME"
}

Parameters
id `'optional'`	Unique EventId that is already registered in SmartSender system.
name `'optional'`	Unique EventName that is already registered in SmartSender system.

Response:

{
  "result": true,
  "data": [{
      "id": "YOUR_EVENT_ID_1",
      "name": "YOUR_EVENT_NAME",
      "description": "YUOR_EVENT_DESCRIPTION",
      "isConversion": true,
      "cost": {
        "value": "91.00",
        "currency": "EUR"
      },
      "createdAt": "2021-07-14 15:51:17",
      "updatedAt": "2021-07-14 15:51:17"
    }],
}

Return value
result	The value indicates that the event was successfully fetched in your account.
true	The event was successfully found.
data	An array of fetched information.
	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

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 ‘id’ must be a non-empty alphanumeric string”
	“Argument ‘name’ must be a non-empty alphanumeric string with a max length of 40 chars”
	“Minimum one unique event identification (id \| name) is 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/custom-event/get';

$body = json_encode([
   "id" => "YOUR_REGISTERED_EVENT_ID",
   "name" => "YOUR_REGISTERED_EVENT_NAME"
]);                           

/**
 * 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

IMPORTANT Do not send more than 10 concurrent API requests.

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 = 'https://api.smartsender.io/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);

Manage Templates#

To create | update | find | get | remove Templates you need to send POST Request with your Access Token in headers to specific URL based on following format

https://api.smartsender.io/v3/template/email/...

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

Create Template#

To create a template you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/template/email/create

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    'name': 'Template name',
    'subject': 'Hello subject',
    'html': 'Hello, World!'
}

Parameters
name `'required'`	Name of your template.
subject `'required'`	The Email subject.
html `'required'`	The full HTML or text content of the template.

Response:

{
    "result": true,
    "templateId": "YOUR_NEW_TEMPLATE_ID"
 }

Return value
result	The request is accepted and queued.
	true	The value indicates that the template was successfully added to your account.
templateId	Unique Template ID assigned in the SmartSender system is used to match the specific Email Template.

Example Error Response JSON:

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

Errors. The reason for the rejection.
result	The request is accepted and queued.
	true	Indicated that the query was successful.
	false	Indicated that the query failed.
Error description	“Argument name must be a non-empty string with max length within 255 characters”
	“Argument subject must be a non-empty string”
	“Twig syntax 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}”
	“Argument subject must be a non-empty string”
	“access token check failed for key\/secret $key\/$accessToken”
	“Argument {argument} required”

PHP Example

$accessToken = "YOUR_API_KEY";
$url         = 'https://api.smartsender.io/v3/template/email/create';

$body = json_encode([
      'name'    => 'Template name',
      'subject' => 'Hello subject',
      'html'    => 'Hello, World!', 
]);
/**
* 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 Template#

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

https://api.smartsender.io/v3/template/email/update

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    'name': 'Template name',
    'subject': 'Hello subject',
    'html': 'Hello, World!', 
    'templateId': 'YOUR_TEMPLATE_ID'
}

Parameters
name `'optional'`	Name of your template.
subject `'optional'`	The Email subject.
html `'optional'`	The full HTML or text content of the template.
templateId `'required'`	YOUR_TEMPLATE_ID from SmartSender system.

Response:

{
         "result": true,
         "templateId": "YOUR_NEW_TEMPLATE_ID"
}

Return value
result	The request is accepted and queued.
	true	The value indicates that the template was successfully updated in your account.
templateId	Unique Template ID assigned in the SmartSender system is used to match the specific Email Template.

Example Error Response JSON:

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

Errors. The reason for the rejection.
result	The request is accepted and queued.
	true	The value indicates that the template was successfully added to your account.
	false	The template creation call rejected.
Error description	“Argument name must be a non-empty string with max length within 255 characters”
	“Argument subject must be a non-empty string”
	“Twig syntax error”
	“Argument html must be a non-empty string”
	“Twig syntax error”
	“Not allowed to edit html in template {templateId}”
	“Argument templateId must be a string”
	“Argument templateId must be a non-empty string”
	“Template {templateId} not found in account”
	“At least one field must be changed”
	“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/template/email/update';

$body = json_encode([
      'name'          => 'Template name',
      'subject'       => 'Hello subject',
      'html'          => 'Hello, World!', 
      'templateId'    => 'YOUR_TEMPLATE_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);

Find Template#

To find a template you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/template/email/find

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
'offset': 4,
'limit':  2 
}

Parameters
offset `'optional'`	Allows you to omit a specified number of rows (number of templates) before the beginning of return rows (events) from the query. The `'default'` is ’20’.
limit `'optional'`	Allows you to limit the number of rows (templates) returned from a query. The `'default'` is ‘0’.

Response:

{
      "result": true,
      "data": [{
         "templateId": "YOUR_TEMPLATE_ID_1",
         "name": "",
         "html": "Hello, World!",
         "templateSource": "dnd",
         "subject": "Hello subject",
         "createdAt": "YYYY-MM-DD HH:mm:ss",
         "updatedAt": "YYYY-MM-DD HH:mm:ss"
      },
      {
         "templateId": "YOUR_TEMPLATE_ID_2",
         "name": "",
         "html": "Hello, World!",
         "templateSource": "dnd",
         "subject": "Hello subject",
         "createdAt": "YYYY-MM-DD HH:mm:ss",
         "updatedAt": "YYYY-MM-DD HH:mm:ss"
      }],
      "totalCount":217,
      "offset":4,
      "limit":2
   }

Return value
result	Indicated that the query was successful.
true	The value indicates that templates were successfully found in your account.
data	An array of fetched information.
	templateId	YOUR_TEMPLATE_ID from SmartSender system.
	name	Template name in the SmartSender system
	html	The full HTML or text content of the template.
	templateSource	Template creation type in SmartSender system. Some types of templates is not possible to update via API to avoid breaking metadata necessary for correct work
		file	HTML template created via upload of the HTML file. `INFO` Can be updated via API.
		text	HTML template created via copying the code to SmartSender admin pannel. `INFO` Can be updated via API.
		rte	HTML template created via Rich Text Editor in SmartSender admin panel. `Warning` Can not be updated via API.
		dnd	HTML template created via Drag & Drop Editor in SmartSender admin panel. `Warning` Can not be updated via API.
		stripo	HTML template imported via Stripo integration. `Warning` Can not be updated via API.
	subject	The Email subject.
	createdAt	Time of template creation `YYYY-MM-DD h:i:s` format
	updatedAt	Time of template last updated in `YYYY-MM-DD h:i:s` format
	totalCount	The number of templates that were found in the request
offset	Allows you to omit a specified number of rows (number of templates) before the beginning of return rows (templates) from the query. The `'default'` is ’20’.
limit	Allows you to limit the number of rows (templates) returned from a query. The `'default'` is ‘0’.

Example Error Response JSON:

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

Errors. The reason for the rejection.
result	The request is accepted and queued.
	true	Indicated that the query was successful.
	false	Indicated that the query failed.
Error description	“Argument name must be a non-empty string with max length within 255 characters”
	“Parameter offset must be an integer”
	“Parameter limit must be an integer”
	“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/template/email/find';

$body = json_encode([
   'offset' =>  4,
   '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;
}
curl_close($ch);

Get Template#

To get a template you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/template/email/get

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
   'templateId' => 'YOUR_TEMPLATE_ID'
}

Parameters
templateId `'required'`	YOUR_TEMPLATE_ID from SmartSender system.

Response:

{
   "result": true,
   "data": {
      "templateId":"YOUR_TEMPLATE_ID",
      "name":"Template name",
      "html":"Hello, World!",
      "subject":"Hello subject",
      "templateSource":"text",
      "createdAt":"YYYY-MM-DD HH:mm:ss",
      "updatedAt":"YYYY-MM-DD HH:mm:ss"
   }
}

Return value
result	The request is accepted and queued.
true	The value indicates that the template was successfully fetched.
data	An array of fetched information.
	templateId	YOUR_TEMPLATE_ID from SmartSender system.
	name	Template name in the SmartSender system
	html	The full HTML or text content of the template.
	subject	The Email subject.
	templateSource	Template creation type in SmartSender system. Some types of templates is not possible to update via API to avoid breaking metadata necessary for correct work
		file	HTML template created via upload of the HTML file. `INFO` Can be updated via API.
		text	HTML template created via copying the code to SmartSender admin pannel. `INFO` Can be updated via API.
		rte	HTML template created via Rich Text Editor in SmartSender admin panel. `Warning` Can not be updated via API.
		dnd	HTML template created via Drag & Drop Editor in SmartSender admin panel. `Warning` Can not be updated via API.
		stripo	HTML template imported via Stripo integration. `Warning` Can not be updated via API.
	createdAt	Time of template creation `YYYY-MM-DD h:i:s` format
	updatedAt	Time of template last updated in `YYYY-MM-DD h:i:s` format

Example Error Response JSON:

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

Errors. The reason for the rejection.
result	The request is accepted and queued.
	true	Indicated that the query was successful.
	false	Indicated that the query failed.
Error description	“Argument templateId must be a non-empty string”
	“Template {templateId} not found in account”
	“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/template/email/get';

$body = json_encode([
   'templateId' => 'YOUR_TEMPLATE_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);

Remove Template#

To remove a template you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/template/email/remove

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
   'templateId' => 'YOUR_TEMPLATE_ID'
}

Parameters
templateId `'required'`	YOUR_TEMPLATE_ID from SmartSender system.

Response:

{
   "result": true,
   "templateId":"YOUR_TEMPLATE_ID"
}

Return value
result	The request is accepted and queued.
true	The value indicates that the template was successfully removed from your account. `IMPORTANT` Template will be removed without recovery option.
templateId	YOUR_TEMPLATE_ID from SmartSender system.

Example Error Response JSON:

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

Errors. The reason for the rejection.
result	The request is accepted and queued.
	true	Indicated that the query was successful.
	false	Indicated that the query failed.
Error description	“Argument templateId must be a non-empty string”
	“Template {templateId} not found in account”
	“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/template/email/remove';

$body = json_encode([
   'templateId' => 'YOUR_TEMPLATE_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 Domains#

To get details of your verified domain names from your account, you need to send POST Request with your Access Token in headers to specific URL based on following format

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

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

IMPORTANT Do not send more than 10 concurrent API requests.

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

Get Domain#

To get the domain details from the account you need to send POST Request with your Access Token in headers to the following URL

https://api.smartsender.io/v3/domain/get

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
  "domainId": "YOUR_REGISTERED_DOMAIN_ID",
  "domain":   "YOUR_REGISTERED_Domain_NAME"
}

Parameters
`IMPORTANT` Minimum one domain identificator (`domainId` \| `domain`) is required.
domainId `'optional'`	Unique domainId that is already registered in the SmartSender system.
domain `'optional'`	Unique DomainName that is already registered in the SmartSender system.

Response:

{
      "result": true,
      "data": {
        "domainId":   "YOUR_DOMAIN_ID",
        "domain":     "YOUR_DOMAIN_NAME",
        "isTrial":  false,
        "createdAt":  "2020-10-02 12:44:03"
      },
      "errors":[]
    }

Return value
result	The value indicates that the domain was successfully fetched from your account.
	true	Domain was successfully fetched.
data	An array of fetched information.
	domainId	Unique domain ID in SmartSender system.
	domain	Verified domain name from your SmartSender account.
	isTrial	Indicates if the domain trial one, automatically generated during registration procedure.
		true	The domain is trial.
		false	The domain is not trial.
	createdAt	Domain creation time in YYYY-MM-DD h:i:s format

Example Error Response JSON

{
    "result": false,
    "data": [],
    "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	“Minimum one unique domain identification (domainId or domain) is required.”
	“Domain not found in your account or not verified”
	“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”
	“Argument ‘domain’ must be a non-empty string”
	“Argument ‘domainId’ must be a non-empty string”

PHP Example:

$accessToken = 'YOUR_API_KEY';
$url  = 'https://api.smartsender.io/v3/domain/get';
$body = json_encode([
    'domainId' => 'YOUR_DOMAIN_ID',
    'domain'   => 'YOUR_DOMAIN_NAME',
]);
/** * 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 Domain#

To fetch a domains from account you need to send POST Request to the following URL

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

IMPORTANT Do not send more than 10 concurrent API requests.

Request body:

{
    "offset": 0,
    "limit": 20
}

Parameters
offset `'optional'`	Allows you to omit a specified number of rows (number of domains) before the beginning of return rows (domains) from the query. The `'default'` is `0`.
limit `'optional'`	Allows you to limit the number of rows (domains) returned from a query. The `'default'` is `20`.

Response:

{
    "result": true,
    "data": [
        {
            "domainId":   "YOUR_DOMAIN_ID_1",
            "domain":     "YOUR_DOMAIN_NAME_1",
            "isTrial":  "false",
            "createdAt":  "2019-02-20 14:32:03"
        },
        {
            "domainId":   "YOUR_DOMAIN_ID_2",
            "domain":     "YOUR_DOMAIN_NAME_2",
            "isTrial":  "false",
            "createdAt":  "2020-10-02 12:44:03"
        }
    ],
    "totalCount": 2,
    "offset": 0,
    "limit": 20,
    "errors": []
}

Return value
result	Indicated that the query was successful.
	true	The value indicates that domains were successfully found in your account.
data	An array of fetched information.
	domainId	Unique domain ID in SmartSender system.
	domain	Verified domain name from your SmartSender account.
	isTrial	Indicates if the domain trial one, automatically generated during registration procedure.
		true	The domain is trial.
		false	The domain is not trial.
	createdAt	Domain creation time in YYYY-MM-DD h:i:s format

Example Error Response JSON

{
    "result": false,
    "data": [],
    "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	“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”
	“Parameter offset must be an integer”
	“Parameter limit must be an integer”

PHP Example:

$accessToken = 'YOUR_API_KEY';
$url         = 'https://api.smartsender.io/v3/domain/find';
$body = json_encode([
   "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);

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.

If the webhook delivery fails, we will make 15 attempts to deliver the webhook before dropping it from the queue.

Number of attempts	Seconds between attempts
3	100
6	600
6	3600

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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
    "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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
    "event": "subscribed",
    "email": "user@example.com",
    "datetime": 1483010763,
    "contactId": "60890ee5890ede9d2c70a077",
    "emailListId": "5537ab2a08d241dc69326b19",
    "phoneNumber": "+155555555",
    "userId": "myUserId-1"
}

Callback URL
event	The type of the event.
	subscribed	The contact subscribed to Email channel in the specified contact list.
	unsubscribed	The contact unsubscribed from Email channel in the specified contact list.
	sms-subscribed	The contact subscribed to SMS channel in the specified contact list.
	sms-unsubscribed	The contact unsubscribed from SMS channel in the specified contact list.
	web-push-contact-desktop-subscribed	The contact subscribed to Desktop Web Push channel in the specified contact list.
	web-push-contact-desktop-unsubscribed	The contact unsubscribed from Desktop Web Pushail channel in the specified contact list.
	web-push-contact-mobile-subscribed	The contact subscribed to Mobile Web Push channel in the specified contact list.
	web-push-contact-mobile-unsubscribed	The contact unsubscribed from Mobile Web Push channel in the specified contact list.
	telegram-contact-channel-subscribed	The contact subscribed to Telegram channel in the specified contact list.
	telegram-contact-channel-unsubscribed	The contact unsubscribed from Telegram channel in 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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
  "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",
      },
      "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
    }
  }
}

Parameters
event	The type of the event.
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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
   "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.
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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
  "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.

IMPORTANT Do not send more than 10 concurrent API requests.

{
  "datetime": 1234567890,
  "event": "web-push-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:

Generate and get JS code snippet

Download and extract Worker File from the archive and add it to the root directory of your website.

Include JS code snippet on every page in your app, immediately before the closing </body> tag.

Properly identify your user.

Call JS API methods to manage your user data.

IMPORTANT Many JS API methods works only if the contact is already in Contact List.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

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

`IMPORTANT` 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.

IMPORTANT Do not send more than 10 concurrent API requests.

User Identification#

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

You should make JS API calls after identifying your user, so that you can associate events with a person in your Contact List.

IMPORTANT Do not send more than 10 concurrent API requests.

WARNING Minimum one unique user identificator (userId | email | phoneNumber ) is required.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script 
    var contact = new _smartSenderContact('user@example.com');
</script>

Parameters
new _smartSenderContact(); `'required'`	Call Web Push Notification One-click Subscription Prompt on any page or by user action.
contact `'required'`	Minimum one unique user identificator (`userId` \| `email` \| `phoneNumber`) is required to identify and match the user in Contact List.

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 Do not send more than 10 concurrent API requests.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _smartSenderContact('USER_UNIQUE_IDENTIFIER');
</script>

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

<script type="text/javascript">
    contact.Add({    
        name: "John Doe",   
        email: "user@example.com",
        phoneNumber: "+15555555",
        userId: "myUserId",
        active: true,
        emailSubscribe: true,
        smsSubscribe: true,
        firstName: "John",
        lastName: "Doe",
        contactBirthday: "YYYY-MM-DD",
        contactLanguage: "en",
        contactGender: "female",
        contactTimezone: "Europe/Tallinn",
        contactScore: 100,
        avatarLink: "img.smartsender.io/g/06c38b4568.jpg",
        facebookLink: "facebook.com/smartsender.io",
        instagramLink: "instagram.com/smartsender",
        linkedInLink: "linkedin.com/company/smartsender",
        twitterLink: "twitter.com/smart_sender",
        tiktokLink: "tiktok.com/smartsender",
        sourceId: "Source_ID_from_SmartSender",
        customerSourceId: "Customer_Source_ID_From_Your_Platform",
        cac: {
            value:      2.05,
            currency:   "USD",
        },
        variables: [
            {name: "stringVariableName", value: "newVariableValue"},
            {name: "dateVariableName", value: "YYYY-MM-DD"}
        ],
    });
</script>

Parameters
contact `'required'`	An array of contact information.
	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` format.
	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
	firstName `'optional'`	Contact’s first name
	lastName `'optional'`	Contact’s last name
	contactBirthday `'optional'`	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
	contactLanguage `'optional'`	Contact’s locale in `ISO 639-1` format
	contactGender `'optional'`	Contact’s gender in `ISO/IEC 5218` format
		0	Not known
		1	Male
		2	Female
		9	Not applicable
	contactTimezone `'optional'`	Contact’s timezone in `ISO 8601` format
	contactScore `'optional'`	Contact Score
	avatarLink `'optional'`	Link to contact’s avatar image.
	facebookLink `'optional'`	Link to contact’s Facebook profile.
	instagramLink `'optional'`	Link to contact’s Instagram profile.
	linkedInLink `'optional'`	Link to contact’s LinkedIn profile.
	twitterLink `'optional'`	Link to contact’s Twitter profile.
	tiktokLink `'optional'`	Link to contact’s TikTok profile.
	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'` (YYYY-MM-DD) 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.

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 Do not send more than 10 concurrent API requests.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _smartSenderContact('USER_UNIQUE_IDENTIFIER');
</script>

Call Contact Update API method and add/update properties of your contact in case of need.

<script type="text/javascript">
    contact.update({    
        name: "John Doe",   
        email: "user@example.com",
        phoneNumber: "+15555555",
        userId: "myUserId",
        active: true,
        emailSubscribe: true,
        smsSubscribe: true,
        desktopWebPushSubscribe: true,
        mobileWebPushSubscribe: true,
        telegramSubscribe: true,
        firstName: "John",
        lastName: "Doe",
        contactBirthday: "YYYY-MM-DD",
        contactLanguage: "en",
        contactGender: "female",
        contactTimezone: "Europe/Tallinn",
        contactScore: 100,
        avatarLink: "img.smartsender.io/g/06c38b4568.jpg",
        facebookLink: "facebook.com/smartsender.io",
        instagramLink: "instagram.com/smartsender",
        linkedInLink: "linkedin.com/company/smartsender"
        twitterLink: "twitter.com/smart_sender",
        tiktokLink: "tiktok.com/smartsender",
        sourceId: "Source_ID_from_SmartSender",
        customerSourceId: "Customer_Source_ID_From_Your_Platform",
        cac: {
            value:      2.05,
            currency:   "USD",
        },
        variables: [
            {name: "stringVariableName", value: "newVariableValue"},
            {name: "dateVariableName", value: "YYYY-MM-DD"}
        ],
    });
</script>

Parameters
USER_UNIQUE_IDENTIFIER `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the DefaultContactList.
contact `'required'`	An array of contact information 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` format.
	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 desktop web push notifications 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 mobile web push notifications or not. The default value is false (unsubscribed).
		true `'optional'`	Subscribe contact to mobile webpush notifications
		false `'default'`	Unsubscribe contact from mobile webpush notification
	telegramSubscribe `'optional'`	You can set if the contact is subscribed to receiving Telegram messages or not. The default value is false (unsubscribed).
		true `'optional'`	Subscribe contact to Telegram messages
		false `'default'`	Unsubscribe contact from Telegram messages
	firstName `'optional'`	Contact’s first name
	lastName `'optional'`	Contact’s last name
	contactBirthday `'optional'`	Contact’s birth date in `ENUM_DATE` (YYYY-MM-DD) format
	contactLanguage `'optional'`	Contact’s locale in `ISO 639-1` format
	contactGender `'optional'`	Contact’s gender in `ISO/IEC 5218` format
		0	Not known
		1	Male
		2	Female
		9	Not applicable
	contactTimezone `'optional'`	Contact’s timezone in `ISO 8601` format
	contactScore `'optional'`	Contact Score
	avatarLink `'optional'`	Link to contact’s avatar image.
	facebookLink `'optional'`	Link to contact’s Facebook profile.
	instagramLink `'optional'`	Link to contact’s Instagram profile.
	linkedInLink `'optional'`	Link to contact’s LinkedIn profile.
	twitterLink `'optional'`	Link to contact’s Twitter profile.
	tiktokLink `'optional'`	Link to contact’s TikTok profile.
	variables `'optional'`	An array of contact variables and their values.
		name `'required'`	Variable name in lowerCamelCase format `IMPORTANT` 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 have higher priority.
	cac `'optional'`	value `'required'`	CAC value in `'ENUM_STRING'` format correspondingly
		currency `'required'`	(EUR, USD) `IMPORTANT` Please use only latin uppercase format. No numbers or other symbols allowed.

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 Do not send more than 10 concurrent API requests.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _smartSenderContact('USER_UNIQUE_IDENTIFIER');
</script>

Initialize event object and call “Fire Event” API method.

<script type="text/javascript">
    var event = new _smartSenderEvent(
        '{{YOUR_REGISTERED_EVENT_ID or EVENT_NAME}}', 
        '{{value}}', 
        '{{USD}}'
    );

    contact.FireEvent(event);
</script>

Parameters
USER_UNIQUE_IDENTIFIER `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the DefaultContactList.
new _smartSenderEvent(); `'required'`	Create event object and add optional attributes in case of need.
FireEvent(); `'required'`	Fire the event to send the data to SmartSender.
customEvent `'required'`	Unique `eventId` or `eventName` that is already registered in SmartSender system.
eventValue `'required'`	Value in `'FLOAT'` or `'INTEGRER'` format correspondingly. `DOT` divider.
eventCurrency `'optional'`		Only `EUR` or `USD`. `IMPORTANT` Latin uppercase format allowed. No numbers or other symbols allowed.

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 Do not send more than 10 concurrent API requests.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _smartSenderContact('USER_UNIQUE_IDENTIFIER');
</script>

Call “Show web push subscription prompt” modal API method.

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

Parameters
USER_UNIQUE_IDENTIFIER `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the DefaultContactList.
ShowPushPrompt(); `'required'`	Call Web Push Notification One-click Subscription Prompt on any page or by user action.

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 Do not send more than 10 concurrent API requests.

IMPORTANT Include this snippet on every page in your app, immediately before the closing </body> tag to initialize JS API and identify your user.

<script type="text/javascript" src="//js.smartsender.io/js/v1/JS_SCRIPT_ID.js>
</script>
<script type="text/javascript">
    var contact = new _smartSenderContact('USER_UNIQUE_IDENTIFIER');
</script>

Call “Generate telegram subscription link” API method.

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

Parameters
USER_UNIQUE_IDENTIFIER `'required'`	The `'email'` address, `'userId'` or `'phoneNumber'` of the recipient stored in the DefaultContactList.
CreateTelegramSubscriptionLink(); `'required'`	Call Telegram bot One-click Subscription Prompt on any page or by user action.
domElementId; `'required'`	HTML element id where the unique Telegram Bot subscription link should be generated.
telegramBotId; `'required'`	Telegram Bot ID which you can get from SmartSender Telegram integration page.
`IMPORTANT` The function returns a Promise object and runs asynchronously
Your button should have specific element id `<a id="some-url-id">Click here to Subscribe to Telegram</a>`, where you need to generate a Telegram Bot subscription link. Learn more by link.