Classic transactional emails

Classic transactional email is for those who prefer to host email code on their own servers. When you send classic transactional email, content is stored for 30 days on our servers for the purpose of sending and previewing, while metadata is kept permanently for reporting.

Classic transactional emails can be sent by API or SMTP, and can be grouped for robust reporting.

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 the plain text version is omitted, it will be automatically generated from the HTML.

Group classic transactional emails for reports

You can send transactional emails without grouping them, however they will all be marked as "Ungrouped emails" in our reporting tools, making it impossible to track results in a meaningful way. To get the most out of reporting, you need assign a group name to related emails.

For example, your "Password reset" emails could all be filed under the one group, whereas your "Order confirmation" emails could form another.

You can group with both the API and SMTP.

Send via API

Below we'll provide examples of how you can send classic transactional via the API. However, we recommend you read the API documentation as the complete and definitive reference for capabilities and syntax.

To send classic transactional email via the API requires authentication, either by OAuth (recommended) or API key. If authenticating by API key, use BasicAuth along with your API key as the username. You may leave the password blank or use a dummy value like "x".

Client IDs

In addition to authenticating, you'll need your client ID. To find the client ID:

1. Click your profile image at the top right, then select Account settings.
2. Click API keys.Your client ID will be listed below your API key.

After you have the client ID, a classic transactional email can be sent as a POST request to our API, with the sender details and content of the email transmitted as a JSON payload.

Request

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

JSON payload

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

Attachments

Attachments are specified in the Attachments array in the JSON payload (in the example above, the array has been left empty). Individual attachments can then be stored as separate objects within that array:

{
  ...
  "Attachments": [
    {
      "Type": "application/pdf",
      "Name": "Invoice.pdf",
      "Content": "base64 encoded content here"
    }
  ]
}

• Type — The MIME type for the file.
• Name — The filename that will be displayed to the recipient.
• Content — Stores the binary data for the file, which must be supplied as a base64-encoded string.

Assign groups for API sends

You can assign a group to a classic transactional email sent via API using the BasicGroup argument in your payload.

Only one group name can be included per payload. For useful reporting, this name should not be unique to each sent payload.

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

Advanced options

By default all emails are tracked for opens and clicks, and we will inline CSS to provide maximum email client support. However, you can turn off these options by passing false in the JSON payload.

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

You can also add transactional recipients to a subscriber list by referencing a list ID. You can find subscriber list IDs with the API.

{
  ...
  "AddRecipientsToListID": "62eaaa0338245ca68e5e93daa6f591e9"
}

To comply with permissions-based email marketing, there are only two situations where doing this is acceptable:

• The recipient has explicitly expressed permission to be sent promotional emails by opting-in at the time of triggering the transactional email.
• The recipient has just completed a purchase from your website or application.

If a user triggers a different type of transactional email, such as a password reset, account confirmation or otherwise, they have not opted-in to a mailing list, and therefore cannot be added to that list as per our anti-spam policy.

Send via SMTP

To start sending classic transactional email via SMTP, you need to point your application to our servers.

SMTP connection details

• Server — smtp.api.createsend.com
• Ports — 587, 25, 465 and 2525 supported, all ports support TLS
• Username — Any valid SMTP token
• Password — Same as username

Credentials

You need an SMTP token to send classic transactional email via SMTP. To locate it:

1. Click Transactional.
2. Click Send with SMTP in the right sidebar. Alernatively, if you haven't sent a transactional email yet, click Send via SMTP.
3. Click Create new in the "SMTP tokens" section to create a new token. If you don't see the "Create new" button, you haven't verified your account. Check your inbox for the email we sent you after you signed up.

Use this SMTP token as both your username and password when sending classic transactional emails via SMTP.

Attachments

When sending attachments via SMTP, filenames containing accented letters (such as é, ñ, or ö) or special letters (like ß or æ) are not supported. For the letters in your filenames, please use only standard Latin characters (A-Z, a-z).

Assign groups for SMTP sends

You can assign a group to a classic transactional email sent via SMTP by passing the following as a header:

X-Cmail-GroupName: XXXXXX

Where XXXXXX is the name you want for the group.

Advanced HTML email header options

By default all HTML emails are tracked for opens and clicks, and we move CSS inline for better email client support. However, you can turn these options off by passing the appropriate header as false instead of true:

• X-Cmail-TrackOpens: true — Whether or not to insert a tracking beacon in the email.
• X-Cmail-TrackClicks: true — Whether or not to rewrite links into trackable links.
• X-Cmail-InlineCSS: true — Whether or not to bring CSS inline.