Sending classic transactional email via our API

You can send classic transactional email via SMTP or our API. On this page we’ll give you a brief overview of setting it up via our API. For more detailed documentation, please see our API page.

Sending a classic transactional email is as simple as sending a POST request via our API:

POST http://api.createsend.com/api/v3.1/transactional/classicEmail/send?clientID=<clientId>

You can retrieve your client ID by clicking on your profile image at the top right, and selecting Manage Account, then API keys.

Authentication

The API currently supports two methods of authentication. We recommend authenticating with OAuth, however we also support authenticating with an API key. For the latter, use BasicAuth along with your API key as the user name. you may leave the password blank or use a dummy value like "x".

Message format

JSON messages are passed in the body of the HTTP POST request:

{
  "Subject": "Password reset request for ABC Widgets",
  "From": "John Smith ",
  "ReplyTo": "support@abcwidgets.com",
  "To": [
    "Jane Smith ",
    "frank@abcwidgets.com"
  ],
  "CC": [
    "Joe Smith "
  ],
  "BCC": null,
  "HTML": "html content goes here",
  "Text": "plain text content goes here",
  "Attachments": [],
  "BasicGroup": "Password Reset",
  "AddRecipientsToList": "bc1aae32-ee0f-11e4-824b-6c4008bc7468"
}

Message content

There are a few things to consider when sending classic transactional emails:

  • You may send to up to a total of 25 recipients across To, CC, and BCC fields.
  • Both the From and To fields can accept a name in addition to an email address, for example, Jane Smith <jane@abcwidgets.com>.
  • You may supply both the HTML and plain text portions of the email. If text is omitted, it will be automatically generated from the HTML.

Grouping email to create reports

Though you can send transactional emails without grouping them, it is impossible to track your results and view meaningful reporting this way. To get the most out of Campaign Monitor functionality and reporting, it is necessary to group related emails together. For example, your "Password reset" emails would be filed under the one group, whereas your "Order confirmation" emails would form another. Emails without a group are filed under "Ungrouped emails" in our reports, and as such won't provide useful feedback.

Include only one group name per message. For useful reporting, this name should not be unique to each sent message.

{
  ...
  "BasicGroup": "Order confirmation"
}

Attachments

Attachments are specified in the Attachments array in the JSON message. Individual attachments can then be stored as separate objects within that array:

  • The "Name" field — is the filename that will be displayed to the recipient.
  • The "Content" field — stores the binary data for the file, which must be supplied as a base64-encoded string.
  • The "Type" field — is the MIME type for the file.
{
  ...
  "Attachments": [
    {
      "Type": "application/pdf",
      "Name": "Invoice.pdf",
      "Content": "base64 encoded content here"
    }
  ]
}

Important: You can only attach PDF files to transactional emails. The file size limit is 25MB.

Advanced options

By default all messages are tracked for opens and clicks, and we will inline CSS to provide maximum email client support. However, you may turn off these options by passing false.

{
  ...
  "TrackOpens": true,
  "TrackClicks": true,
  "InlineCSS": true
}

Adding recipients to a subscriber list

When sending transactional email, you have the option to opt-in certain recipients to a marketing subscriber list.

IMPORTANT: By taking this path you are asserting that you have permission to send non-transactional emails to these recipients in the future.

To add transactional recipients to a subscriber list, you're going to need the ID of the list you want to import to. To do so, open Lists & Subscribers, and load the list of your choice. Under its name, click change name/type, and the list ID can be found under "API Subscriber List ID."

Copy the list ID, then add the following to your API call:

{
  ...
  "AddRecipientsToList": "XXXXXX"
}

Where XXXXXX is the list ID that you wish to add to.