Getting Started

Getting started with SimplerSES is easy. Sign up for a new account and get 10,000 free credits to start you off.

You will also need an Amazon Simple Email Service account. Sign up at if you do not already have one.

Set up Amazon SES

Grant permissions for simplerSES to use Amazon SES

In order to link up simplerSES with your Amazon account, you need to create a new user from within Amazon IAM, and enter in it's access credentials to your SimplerSES settings page.

Visit the IAM Management Console and create a new user called 'simplerses_user' via the users tab in the sidebar.

You should be given an 'Access Key Id' and a 'Secret Access Key'. Save these permissions for now.

Select the user, click on the permissions tab and click Attach User Policy. Select the 'Amazon SES Full Access' policy token. Repeat the step and add the 'Amazon SNS Full Access' policy to the user.

Enter the access credentials that you recorded down in your simplerSES Account Settings

Verifying email addresses

Amazon requires you to verify every email that you wish to use in your from address field.

You can manage these addresses directly from the Amazon SES console

Requesting production access

Your Amazon SES account is created in sandbox mode. While in sandbox mode you can only send emails to verified email addresses. Visit and follow the instructions to apply for production access.

Setup DKIM signing

It is recommended you setup DKIM signing to improve deliverability of your emails.

You can enable DKIM signing by visiting the Amazon SES console and adding the domain used in your from address to the verified domains list.

Campaigns and Templates


Create campaigns for each category of emails that you send out, e.g. 'welcome', 'day3', 'forgot_password'.

You can enter in the dynamic fields that are available to a campaign when you create/edit it. These fields can be used in your email templates and will be replaced by the respective data from your subscriber lists or from within your API call.


Templates contain the email content for your campaigns.

You can create multiple templates within a campaign to test out different variations. You can edit/activate/deactivate them on the fly. For each email request, SimplerSES will randomly select one of the active templates in that Campaign.

Dynamic fields

Dynamic fields must be defined at the campaign level. Templates may use any or all of the dynamic fields defined for a campaign.

These dynamic fields can then be used within any template using the {{foo}} notation.

All dynamic fields defined for a campaign should be part of the API call. SimplerSES will fail over to the default value for any missing fields.

Subscriber Lists

Managing Subscriber lists

Subscriber Lists allow you to manage and control your contact emails online. Simply upload your subscribers data and deliver email campaigns at the click of a button.

The csv file must be in a special format: The first row of the csv must be the name of column. The first column of data should always be the email addresses of your users and have the header 'email'. Names should be alphanumeric and not contain spaces.

Download the sample file to ensure your data is in the correct format before uploading. [sample.csv]

Sending Newsletters to a Subscriber List

You can deliver emails to a subscriber list, simply by clicking on the 'Deliver Campaign' button and selecting the campaign to deliver with. Pay special attention to the campaign you are selecting as the delivery cannot be cancelled once confirmed.

List Segments

List Segments allow you to split your subscriber lists into individual sets based on search criteria.

Unsubscribe Links

To track unsubscriptions for emails, add the 'data-unsubscribe' attribute to your unsubscription links.

<a href='' data-unsubscribe='1'>Example Unsub</a>



The campaign graph shows you the overall performance of a campaign up to the last 6 months. The emails sent at each hour and the corresponding opens/clicks/bounces from those emails. You can select the range of time for which you wish to see the graph data.

The Campaign breakdown table shows the delivery breakdown for each template over the range selected in the Campaign graph. You can use this breakdown to quickly see which emails performed better over a certain time range.

Delivery reports

You can view detailed delivery reports for manual campaign deliveries.


Whitelabel URLs

Normally SimplerSES generates tracking links in your emails of the form:

<a href='' />

You can setup your own domain to show up in tracking links instead. Simply enter in your domain in your account options. Note that you need to setup a CNAME record from your domain which points to

<a href='' />

API Access

All API calls must be made as POST requests.

Sending Emails

The API accepts the following parameters:

Key name Description
auth_token [string] your simplerSES API access token
campaign_name [string] name of an existing campaign
from [string] verified email to be used as the from email address.
Optional if the default from email is set in Account Settings.
to [csv] emails in the to field
cc [optional csv] emails in the cc field
bcc [optional csv] emails in the bcc field
custom_fields [optional object] key value pairs which are used to set dynamic content in your email.
Any keys not defined in the specified campaign are ignored.
Note: Amazon's send limits apply. The total number of emails in the to, cc and bcc fields combined should not exceed 50.

Managing subscribers

Create/Update subscribers{list_name}/subscribers
Key name Description
auth_token [string] your simplerSES API access token
email [string] email for the subscriber
custom_fields [hash] Custom Fields available for the subscriber.

Unsubscribe subscribers{list_name}/subscribers/unsubscribe
Key name Description
auth_token [string] your simplerSES API access token
email [string] email for the subscriber

Sample Codes


url = ''
options = {
  query: {
    auth_token: 'your_auth_token',
    campaign_name: 'welcome_email',
    from: '',
    to: ',',
    custom_fields: {username: 'jimbo', full_name: 'Jim Bob' }
response =, options)
data = JSON.parse(response.body)
puts data['type']
puts data['message']
$url = '';
$params = array(
  'auth_token' => 'your_auth_token',
  'campaign_name' => 'welcome_email',
  'from' => '',
  'to' => ',',
  'custom_fields' => array('username' => 'jimbo', 'full_name' => 'Jim Bob')
$params = http_build_query($params);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);

curl -H "Content-type: application/json" -X POST -d '{"auth_token":"your_auth_token", "campaign_name":"welcome_campaign", "to":",", "from":"", "custom_fields":{"username":"jimbo", "full_name": "Jim Bob"}}'

Error Messages

In case of an Amazon SES error, SimplerSES will return the Amazon SES error code and message.

{"type":"error", "message":"The security token included in the request is invalid.", "status":"InvalidClientTokenId"}

For a detailed list of Amazon SES error codes visit

SimplerSES errors have the status "Failure". You should manually review these errors as they are likely to indicate invalid API calls.

Referral Program

If you are a SimplerSES user, you can earn a commission for every new customer you refer to us. It's as simple as sharing your unique referral link - found in your account settings page -.

How much is the commission?

The referral program pays 10% of all purchases made by your referral for the first month after signup.

When/how do I get paid?

All payments are consolidated and processed on the 1st of every month and must be sent to a valid PayPal account.

How long do referral links last after a user clicks on them?

For every user who clicks on your link, SimplerSES sets a browser cookie which is valid for 60 days.

If the user signs up and makes a purchase anytime in that period, you will receive 10% of all purchases made in the 30 days after they signup.