SmartSender API 2.0: Get Started

Last updated: 19 February 2017

With SmartSender API 2.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 tech@sndmart.com email.

Send a new message .../send

To send a new message you need to send POST Request to the following URL:

https://api.sndmart.com/send

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

Send a new transactional message via SmartSender

Example JSON Request

                        {
    'key': 'your_id',
    'secret': 'your_secret',
    'message': {
        'from_email': 'example@domain.com',
        'from_name': 'sender name',
        'reply_to': [
            {
                'name': 'Support',
                'email': 'Support@domain.com'
            }
        ],
        'subject': 'Sample Subject!',
        'to': [
            {
                'name': 'contact name',
                'email': 'exampleReceiver@domain.com'
            }
        ],

        'headers': {},
        'tags': ['tag1', 'tag2'],
        'text': 'Some awesome text',
        'html': 'Some awesome text'
    }
}
                    

Parameters

key

'required'

A valid API key

'required'

secret

'required'

User secret key for authorization.

Warning: Keep your API key secret!

message

'required'

The information in the message to send:

from_email

'required'

The sender email address email

'required'

from_name

'required'

Optional from name to be used

'optional'

reply_to []

'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_email will be used instead

name

'optional'

The optional display name to use for the reply-to recipient

'optional'

email

'required'

The email address of the reply-to recipient

'required'

subject

'required'

The message subject

'required'

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

name

'optional'

The optional display name to use for the recipient

'optional'

email

'required'

The email address of the recipient

'required'

headers

'optional'

Optional extra headers to add to the message (most headers are allowed)

'optional'

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.

You can add custom tags to your messages to ease stats collections (mark templates, campaigns, etc). WARNING: A single tag - must not start with an underscore

'optional'

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.

'optional'

html

'required'

The full HTML or text content to be sent

'required'

Example Positive Response JSON

                        {
    'message_id': '5537ab2a08d241dc69326b19',
    'result': 1
}
                    

Return Value the sending results for a single recipient

message

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:

1

The message is accepted and queued

0

The message is rejected

Example Error Response JSON

                        {
    'validation_errors': {
        'from_name': [
            'This field is required.'
        ]
    },
    'result': 0,
    'error': 'Validation errors'
}
                    

Errors.
The reason for the rejection.

validation_errors

The parameters passed to the API call are invalid or not provided when required

Validation errors

The message contains invalid data

Unauthorized

API authorization failed

result

The sending status of the recipient:

1

The message is accepted and queued

0

The message is rejected

error

Error type

PHP Example

<?php

$url = 'https://api.sndmart.com/send';
$data = json_encode([
    'key'       => '%your_key%',
    'secret'    => '%your_secret%',
    'message'   => [
        'from_email'    => 'exampleSender@domain.com',
        'from_name'     => 'sender name',
        'reply_to'            => [
            [
                'name'      => 'support',
                'email'     => 'support@domain.com'
            ]
        ],
        'subject'       => 'Sample Subject!',
        'to'            => [
            [
                'name'      => 'contact name',
                'email'     => 'example@domain.com'
            ]
        ],
        'text'          => 'Some awesome text',
        'html'          => 'Some awesome text'
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: '.strlen($data)
    ]
);

var_dump(curl_exec($ch));
                

Get statistics .../message

SmartSender tracks and collects many different events and generates event statistics which are available in your Control Panel. This data is also available via an API. You can request statistics on specific message or a group of messages. To get the statistics you need to send a JSON request to the following URL

https://api.sndmart.com/message

In the JSON request you need to mention IDs of messages stats’ of which you need.

Only 100 message IDs are allowed in one request

Example JSON Request

                        {
    'key': 'your_id',
    'secret': 'your_secret',
    'ids': [
        '5537ab2a08d241dc69326b19',
        '5537ab2a08d241dc69326b20'
    ]
}
                    

Callback URL

key

'optional'

Valid account id

You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

'optional'

secret

'required'

User secret for request authorization.
Warning: Keep your API key secret!
You can find your secret in you profile settings page: https://partner.sndmart.com/profile/

ids

'required'

List of message ID numbers. You can include only 100 IDs in one request.

'required'

Example Positive Response JSON

                        {
    'messages': [
        {
            'id': '5537ab2a08d241dc69326b19',
            'from_email': 'exampleSender@domain.com',
            'from_name': 'sender name',
            'subject': 'Sample Subject!',
            'to': [
                {
                    'name': 'contact name',
                    'email': 'exampleReceiver@domain.com'
                }
            ],
            'headers': {},
            'text': 'Some awesome text',
            'html': 'Some awesome text',
            'events': [
                {
                    'event': 'read',
                    'datetime': '2015-04-27 12:18:58.592000'
                },
                {
                    'datetime': '2015-04-27 12:19:07.145000'
                },
                {
                    'event': 'read',
                    'datetime': '2015-04-27 12:19:11.430000'
                },
                {
                    'datetime': '2015-04-27 13:02:40.256000'
                },
                {
                    'event': 'read',
                    'datetime': '2015-04-27 14:56:31.165000'
                }
           ]
       }
    ],
    'result': 1
}
                    

Messages
returns a list of requested messages.

result

The sending status of the recipient:
1 - The message is accepted and queued
0 - The message is rejected

message

id

The message unique identification number in SmartSender system

from_email

The sender email address

from_name

Optional from name to be used

subject

The message subject

to

A single recipient's information.

email

The email address of the recipient required

name

The optional display name to use for the recipient

headers

Optional extra headers to add to the message (most headers are allowed)

events

Email statistics includes detailed information on each message in the account. List of available events:

sent

The send status is assigned as soon as SmartSender received a message.

delivered

The send status is assigned as soon as SmartSender sent the message and it was accepted by the recipient ISP server.

read

The read status is assigned every time this message has been opened by the user. The message includes information on each read.

click

The click status is assigned every time tracked URLs in this message have been clicked by the user. The message includes information on each click.

hard

The time and hard-bounce code received from the ISP

soft

The time and soft-bounce code received from the ISP

Example Error Response JSON

                        {
	'error':	['Require \'ids\' arguments to query \'messages\''],
	'result':	0
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Authorization needed

Missing API key parameter

Require \'ids\' arguments to query \'messages\'

Missing valid message ID's

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url = 'http://api.sndmart.com/message';
$data = json_encode([
    'key'       => '%your_key%',
    'secret'    => '%your_secret%',
    'ids'       => [
        '58a819c6f0152ter32323234',
        '58a819c6f0152sda43423432',
        '58a819c6f013434243242343'
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: '.strlen($data)
    ]
);

var_dump(curl_exec($ch));
                

Add new contact address to email list .../contacts/add

To add a new contact to email address list you need to send POST Request with your Access Token in headers to the following URL:

https://partner.sndmart.com/api/rest/email-list/contacts/add

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

Below you can see the table with required parameters.

Example JSON Request

                        {
    'emailListId': 'your_id',
    'contacts': [
        {
            'name': 'contact name',
            'email': 'exampleReceiver@domain.com',
            'active': true,
            'variables': [
                {
                    'name': 'onlyLowerCamelCase1',
                    'value': 'bar'
                },
                {
                    'name': 'onlyLowerCamelCase2',
                    'value': 'bar'
                }
            ]
        }
        {
            'name': 'contact name',
            'email': 'exampleReceiver2@domain.com',
            'active': true,
            'variables': [
                {
                    'name': 'onlyLowerCamelCase1',
                    'value': 'bar'
                },
                {
                    'name': 'onlyLowerCamelCase2',
                    'value': 'bar'
                }
            ]
        }
    ],
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'required'

ID of the email list to which you want to add the new contact.
The list should be already created in your account on Lists page: https://partner.sndmart.com/list/list

contacts []

'required'

An array of contact information.
You can add more than one contacts at once.

name

'optional'

The optional display name to use for the recipient

email

'required'

The email address of the recipient

'required'

active []

'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

variables []

'optional'

An array of contact variables and their values.

name

'required'

lowerCamelCase 'required'
IMPORTANT: Please use only latin lowerCamelCase format. No numbers or other symbols allowed.

value

'required'

Bar

'required'

Example Positive Response JSON

                        {
    'result'  : true
}
                    

Return value

result

The value indicates that the contact was successfully added to your email list.

true

Contact was successfully added

Example Error Response JSON

                        {
    "Error_stack":[
        "Email list with id XXX not found"
    ],
    "requestId":"NNN"
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Not valid type for argument \"contacts\" in query \"addContactToEmailList\

Empty email field

Contact with email example@domain.com already exists

Address already exist

Variable name XXX not found in defined email list variables! Try to add it first!

Wrong or empty variable included

Invalid variable type on XXX

Wrong or missing variable value

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/email-list/contacts/add';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId' => 'XXX',
    'contacts'    => [
        [
            'email'     => 'example@domain.com',
            'name'      => 'contact name',
            'active'    => true,
            'variables' => [
                [
                    'name'  => 'id',
                    'value' => '1234567890'
                ],
                [
                    'name'  => 'regDay',
                    'value' => '2016-12-31'
                ],
            ],
        ],
    ],
]);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Remove contact from the list .../remove

To remove a contact from the email address list you need to send POST Request with your Access Token in headers to the following URL:

https://partner.sndmart.com/api/rest/email-list/contacts/remove

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

Below you can see the table with required parameters.

Example JSON Request

                        {
    'emailListId': 'XXX',
    'emails': [
        'example1@domain.com',
        'example2@domain.com',
    ]
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'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.sndmart.com/list/list

emails []

'required'

An array of contact information.
You can remove more than one contacts at once.

email

'required'

The email address of the recipient

'required'

Example Positive Response JSON

                        {
    'result'  : true
}
                    

Return value

result

The value indicates that the contact was successfully removed your email list.

true

Contact was successfully removed

Example Error Response JSON

                        {
    'Error_stack':[
        'Not valid type for argument \'emails\' in query \'removeContact\'
    ],
    'requestId':'NNN'
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Require \"emails\" arguments to query \"removeContact\"

Empty email field

Not valid type for argument \"emails\" in query \"removeContact\"

Invalid or empty email address included

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/email-list/contacts/remove';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId'   => 'XXX',
    'emails'        =>  [
        'example1@domain.com',
        'example2@domain.com',
      ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Update contact data .../contacts/update

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

https://partner.sndmart.com/api/rest/email-list/contacts/update

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

Below you can see the table with required parameters.

Example JSON Request

                        {
  emailListId: "your_id",
  contact: "example@domain.com",
  parameters: {
    name: "contact name",
    email: "newExample@domain.com",
    active: true,
    variables: [
      {
        name: "foo",
        value: "bar"
      },
      {
        name: "foo1",
        value: "bar"
      }
    ]
  }
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'required'

ID of the email list where the contact to be updated belongs.
The list should be already created in your account on Lists page:

https://partner.sndmart.com/list/list

contact

'required'

The email address of the recipient you want to update

'required'

parameters []

'required'

An array of contact information.
You can update only one contact at once.

name

'optional'

The optional display name to use for the recipient

email

'optional'

The new email address of the recipient

active []

'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

variables []

'optional'

An array of contact variables and their values.

name

'required'

lowerCamelCase 'required'
IMPORTANT: Please use only latin lowerCamelCase format. No numbers or other symbols allowed.

value

'required'

Bar

'required'

Example Positive Response JSON

                        {
    'result'  : true
}
                    

Return value

result

The value indicates that the contact was successfully updated.

true

Contact was successfully updated

Example Error Response JSON

                        {
    "Error_stack":[
        "Require \"contact\" arguments to query \"updateContact\"
    ],
    "requestId":"NNN"
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Require \"contact\" arguments to query \"updateContact\"

Not valid or missing email field

Contact example@domain.com not found!

Wrong or empty email address entry

Require \"parameters\" arguments to query \"updateContact\"

Parameters not included

Not valid type for argument \"parameters\" in query \"updateContact\"

Wrong or empty new email address entry

Variable name XXX not found in defined email list variables! Try to add it first!

Wrong or empty variable included

Invalid field \"XXX\" on VariableHolderInput

Wrong or missing variable argument

Invalid field \"XXX\" on VariableHolderInput

Wrong or missing variable value

Variable name XXX not found in defined email list variables! Try to add it first!

Wrong or empty variable included

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/email-list/contacts/update';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId' => 'XXX',
    'contact'     => 'example@domain.com',
    'parameters'  => [
    'name'        => 'newName',
    'email'       => 'newExample@domain.com',
    'active'      =>  true,
    'variables'   => [
          [
            'name'    => 'newVariableName1',
            'value'   => 'newVariableValue1'
          ],
          [
            'name'    => 'newVariableName2',
            'value'   => '2016-12-31'
          ],
        ]
    ]

]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Update contact batch data .../contacts-batch/update

To update a contact data for group of addresses at once from the email address list you need to send POST Request with your Access Token in headers to the following URL:

https://partner.sndmart.com/api/rest/email-list/contacts-batch/update

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

Below you can see the table with required parameters.

Example JSON Request

                        {
    emailListId: "your_id",
    contacts: [
        {
            contact: "example@domain.com",
            parameters: {
                name: "contact name",
                email: "example1@domain.com",
                active: true,
                variables: [
                  {
                    name: "foo",
                    value: "bar"
                  },
                  {
                    name: "foo1",
                    value: "bar1"
                  }
                ]
            }
        },
        {
            contact: "newExample@domain.com",
            parameters: {
                name: "contact name",
                email: "example2@domain.com",
                active: true,
                variables: [
                  {
                    name: "foo",
                    value: "bar2"
                  },
                  {
                    name: "foo1",
                    value: "bar3"
                  }
                ]
            }
        },
    ]
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'required'

ID of the email list where the contact to be updated belongs.
The list should be already created in your account on Lists page: https://partner.sndmart.com/list/list

contacts []

'required'

An array of information on contacts batch you want to update.
You can update only 100 contacts at once.

contact

'required'

The email address of the recipient you want to update

'required'

parameters []

'required'

An array of contact information.
You can update only one contact at once.

name

'optional'

The optional display name to use for the recipient

email

'optional'

The new email address of the recipient

active []

'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

variables []

'optional'

An array of contact variables and their values.
Important: Variable names must be in lowerCamelCase format.

name

'required'

lowerCamelCase 'required'
IMPORTANT: Please use only latin lowerCamelCase format. No numbers or other symbols allowed.

value

'required'

Bar

'required'

Example Positive Response JSON

                        {
    'result': true,
    'updated':[
        '5882312af015271080158af6',
        '5882312af015271080158af7',
        '5882312af015271080158af8'
    ],
    'errors':[]
}
                    

Return value

You will get a list of contact id's for successfully added addresses and list of errors for failed ones.

result

The value indicates that the contact was successfully updated.

true

Contact was successfully updated

updated []

An array of ID's of contacts that were successfully updated.

errors []

An array of failed updates and error messages with description of why request was rejected.

See the list of error messages below

Example Error Response JSON

                        {
    'result': true,
    'updated':[
        '5882312af015271080158af6',
        '5882312af015271080158af7',
        '5882312af015271080158af8'
    ],
    'errors':[
        'Unable to find email example@domain.com in email list listId'
    ]
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

Current limitation is 100 contacts per request!

More than 100 contacts in one request

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Require \"contact\" arguments to query \"updateContact\"

Not valid or missing email field

Unable to find email example@domain.com in email list listId

Wrong or empty email address entry

Require \"parameters\" arguments to query \"updateContact\"

Parameters not included

Not valid type for argument \"parameters\" in query \"updateContact\"

Wrong or empty new email address entry

Variable name XXX not found in defined email list variables! Try to add it first!

Wrong or empty variable included

Invalid field \"XXX\" on VariableHolderInput

Wrong or missing variable argument

Invalid field \"XXX\" on VariableHolderInput

Wrong or missing variable value

Variable name XXX not found in defined email list variables! Try to add it first!

Wrong or empty variable included

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/email-list/contacts-batch/update';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId' => 'XXX',
    'contacts' => [
        [
            'contact'     => 'example1@domain.com',
            'parameters'  => [
            'name'        => 'newName',
            'email'       => 'example3@domain.com',
            'active'      =>  true,
            'variables'   => [
                  [
                    'name'    => 'newVariableName1',
                    'value'   => 'newVariableValue1'
                  ],
                  [
                    'name'    => 'newVariableName2',
                    'value'   => '2016-12-31'
                  ],
                ]
            ]
        ],
        [
            'contact'     => 'example2@domain.com',
            'parameters'  => [
            'name'        => 'newName',
            'email'       => 'example4@domain.com',
            'active'      =>  true,
            'variables'   => [
                  [
                    'name'    => 'newVariableName1',
                    'value'   => 'newVariableValue1'
                  ],
                  [
                    'name'    => 'newVariableName2',
                    'value'   => '2016-12-31'
                  ],
                ]
            ]
        ]
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Add variable to email list .../variables/add

To add a new variable to email address list you need to send POST Request with your Access Token in headers to the following URL:

https://partner.sndmart.com/api/rest/email-list/variables/add

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

Below you can see the table with required parameters.

Example JSON Request

                        {
  emailListId: "your_id",
  variablesMetadata: [
    {
      name: "newOnlyLowerCamelCaseVariable1",
      type: STRING
    },
    {
      name: "newOnlyLowerCamelCaseVariable2",
      type: DATE
    }
  ]
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'required'

ID of the email list to which you want to add the new variable.
The list should be already created in your account on Lists page: https://partner.sndmart.com/list/list

variablesMetadata []

'required'

Details of variables

name

'required'

lowerCamelCase 'required'
IMPORTANT: Please use only latin lowerCamelCase format. No numbers or other symbols allowed.

type

'required'

ENUM_STRING

'required'

No specific format required

name

'required'

lowerCamelCase 'required'
IMPORTANT: Please use only latin lowerCamelCase format. No numbers or other symbols allowed.

type

'required'

ENUM_DATE

'required'

Required format 'YYYY-MM-DD'

'required'

Example Positive Response JSON

                        {
    'result'  : true
}
                    

Return value

result

The value indicates that the contact was successfully updated.

true

Contact was successfully updated

Example Error Response JSON

                        {
    'error_stack':[
        'Not valid type for argument \'variablesMetadata\' in query \'addVariablesMetadata\'
    ],
    'requestId':'NNN'
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Not valid type for argument \"variablesMetadata\" in query \"addVariablesMetadata\

Not valid type for argument for variable

Unexpected token \"COLON\"

No name/type data

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/email-list/variables/add';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId'         => 'XXX',
    'variablesMetadata'   => [
        [
          'name' => 'onlyLowerCamelCase1',
          'type' => 'ENUM_STRING'
        ],
        [
          'name' => 'onlyLowerCamelCase2',
          'type' => 'ENUM_DATE'
        ],
    ],
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Send Triggered Email .../mailer/send

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

https://partner.sndmart.com/api/rest/mailer/send

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

Below you can see the table with required parameters.

Example JSON Request

                        {
    emailListId: ‘XXX’,
    contact: "example@domain.com",
    templateId: "XXX",
    tags: [
        "tag1",
        "tag2"
    ]
}
                    

Parameters

access-token

'required'

User secret key for request authorization.
Warning: Keep your API key secret!
You should include your secret key into your request header for authorization.
You can find your secret key in you profile settings page: https://partner.sndmart.com/profile

emailListId

'required'

ID of the email list to which the contact belongs.
The list should be already created in your account on Lists page: https://partner.sndmart.com/list/list

contact

'required'

The email address of the recipient

'required'

templateId

'required'

If of the template you want to send. The template should be already created in your account on Templates page: https://partner.sndmart.com/template/

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

'optional'

Example Positive Response JSON

                        {
    'result':true,
    'messageId':'XXX',
    'error':null
}
                    

Return value

result

The value indicates that the triggered message was successfully sent out.

true

Message was successfully sent out

messageId

The message unique identification number in SmartSender system. With this ID number you can get all the statistics on each sent message.

error

null

Example Error Response JSON

                        {
    'error_stack':[
        'Require \"templateId\" arguments to query \"triggerSubscription\"'
    ],
    'requestId':'NNN"
}
                    

Errors.
The reason for the rejection.

errors

API Key XXX does not exist.

error_stack

Error messages with description of why request was rejected.

Email list with id XXX not found

Wrong Contact List ID

Contact example@domain.com not found!

Wrong or empty email address entry

Require \"templateId\" arguments to query \"triggerSubscription\"

Wrong or empty template ID entry

Unexpected token "name" of value "contacts" ("end of print statement" expected) in "__string_template__XXX" at line XXX.

The Contact List is missing a variable used in the template you try to send. Add the variable first to the Contact list.

requestId

Unique error ID which can help our support team to find your request and solve the problem.

PHP Example

<?php

$url         = 'https://partner.sndmart.com/api/rest/mailer/send';
$accessToken = 'XXX';
$data        = json_encode([
    'emailListId' => 'XXX',
    'contact'     =>  'example@domain.com',
    'templateId'  =>  'XXX',
    'tags'        =>  [
        'tag1',
        'tag2'
    ]
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt(
    $ch, CURLOPT_HTTPHEADER,
    [
        'Content-Type: application/json',
        'Content-Length: ' . strlen($data),
        sprintf('access-token: %s', $accessToken),
    ]
);

var_dump(curl_exec($ch));
                    

Webhooks

SmartSender can make an HTTP POST 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 to your Callback URL will contain following information:

Specific Message Callback Events

                        {
    "datetime": 1234567890,
    "event": "read",
    "email": "example@domain.com",
    "id": "5537ab2a08d241dc69326b19"
}
                    

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.

reject

The email address is in black list

email

The email address of the recipient

id

The message unique identification number in SmartSender system

Contact Management Callback Events

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

Callback URL

event

The type of the event.

removed

The contact was removed from the specified contact list.

subscribed

The contact was subscribed to the specified contact list.

unsubscribed

The contact was unsubscribed from the specified contact list.

email

The email address of the recipient

datetime

The time when the event was generated in the system provided as Unix epoch seconds.

contactId

The message unique identification number for the contact in SmartSender system

emailListId

ID of the email list to which you want to add the new variable. The list should be already created in your account on Lists page: https://partner.sndmart.com/list/list

DNS Settings 'required'

To be able to send via SmartSender you'll need to add SPF and DKIM records before you can send email via your account.

SPF

SPF is another DNS-based email authentication mechanism. If you do not yet have an SPF record, you should to add one for your domain. At a minimum, the value should be the following if you are only sending mail via SmartSender for that domain:

                        v=spf1 include:_spf.sndmart.click ?all
                    

Instructions

If you already have a TXT record with SPF information, you will need to add SmartSender’s servers to that record by adding: include:_spf.sndmart.click in the record (before the last operator, which is usually ?all, ~all or -all).

DKIM

DKIM is a DNS-based email authentication mechanism that helps SmartSender more effectively send mail on your behalf by allowing receivers to verify that we have permission to send your email.

                        v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQsd1Aqf76HSFl1pHlNTNXV+RheaaXRg022UvaB/Vfc1vYHSh/lUl1CW0IHuUnxVEy5XQlS2Xg0WUJXHedWskzFlYZL0uhb1q3XOaFIC1t7wXBzOfye76JK3UVu93RtBF+u8ohyIiN4I4bRsCGJcCoPm7rxhMIZWtuuHlGyCVERQIDAQAB
                    

Instructions

To enable DKIM, create TXT record for sndmart._domainkey.yourdomain.com (just replace yourdomain.com with the domain you are setting up) with the following value:

DomainKey

DomainKeys is a e-mail authentication system designed by Yahoo to verify the DNS domain of an e-mail sender and the message integrity.Highly Recommended to use DomainKey if you plan to send high volumes of emails to Yahoo.

                        k=rsa; t=y; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDXXcn/chLfDn45y2vTerKuOoe4D3R4x5v3WGuJE+ttIlphvI2UIJ+L6g695XzUVW9186VHhwkSPicxohqTZq4kHRL2byNIDKhWa6e8Bwh9jU0y0D5NNDdH366+34vwoc5a5oVFHsiak9jfN7O7J6B8fOElEFmZEsgQjLHmU1VjiwIDAQAB
                    

Instructions

To enable DomainKey, create TXT record for sm1._domainkey.yourdomain.com (just replace yourdomain.com with the domain you are setting up) with the following value:

DMARC

SmartSender doesn't currently validate DMARC records for your sending domains, but it is Highly Recommended to use DMARC in addition to SPF and DKIM. Your DMARC implementation does not depend on the usage of SmartSender. For details on setting up DMARC for your domain, we recommend using a guide like this one from Google or Kitterman.

                        _dmarc IN TXT v=DMARC1; p=none; sp=none; rua=mailto:postmaster@yourDomain.com 
                    

Instructions

We recommend running DMARC in notification mode only (with p=none in the DMARC record to indicate that mail that fails should be delivered normally) to get an idea for how much mail would be affected by switching to a stricter policy.

Copy and pass this instructions to your system administrator

                        @ IN MX 5 mail1.sndmart.com

@ IN TXT v=spf1 include:_spf.sndmart.click include:_spf.sndmart.com ?all

sndmart._domainkey IN TXT v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDQsd1Aqf76HSFl1pHlNTNXV+RheaaXRg022UvaB/Vfc1vYHSh/lUl1CW0IHuUnxVEy5XQlS2Xg0WUJXHedWskzFlYZL0uhb1q3XOaFIC1t7wXBzOfye76JK3UVu93RtBF+u8ohyIiN4I4bRsCGJcCoPm7rxhMIZWtuuHlGyCVERQIDAQAB

sm1._domainkey IN TXT k=rsa; t=y; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDXXcn/chLfDn45y2vTerKuOoe4D3R4x5v3WGuJE+ttIlphvI2UIJ+L6g695XzUVW9186VHhwkSPicxohqTZq4kHRL2byNIDKhWa6e8Bwh9jU0y0D5NNDdH366+34vwoc5a5oVFHsiak9jfN7O7J6B8fOElEFmZEsgQjLHmU1VjiwIDAQAB

_dmarc IN TXT v=DMARC1; p=none; sp=none; rua=mailto:postmaster@your-domain.com