Transactional

Transactional emails are triggered by your own site or app, typically in response to a user's action, such as an order confirmation or a plan renewal. You can send transactional email in one of two ways:

  • Smart email - The content is defined inside Campaign Monitor and is triggered via your application by supplying recipients and, optionally, email variables to merge into the content.
  • Classic email - You supply the entire message content at the time of sending.

Unlike the rest of our API, all /transactional endpoints support only JSON and are subject to rate limiting.


Smart email listing

To get a list of smart transactional emails, filtered by status:

GET https://api.createsend.com/api/v3.1/transactional/smartEmail?status={all|draft|active}&clientID={:clientId}

status string, optional. Default: all.
clientID string, optional. Note to agencies: if you are using an account API key or OAuth, this is required as you need to specify the client. This is not necessary if you use a client-specific API key.

Expected response:
[
    {
        "ID": "fg84jd3vbask48fjh59dnfls",
        "Name": "Welcome email",
        "CreatedAt": "2014-01-15T16:09:19-05:00",
        "Status": "Active"
    },
    ...
]
Error responses:

Please see our response status codes for potential error responses to any API request.

If you receive a 400 Bad Request response,the possible errors which may be included in the body are:

  • 932: Invalid status parameter Must be one of "all", "active", or "draft"
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Smart email details

To get the details for a smart transactional email:

GET https://api.createsend.com/api/v3.1/transactional/smartEmail/{:smartEmailID}

smartEmailID The ID of the smart email to send

Expected response:
{
    "SmartEmailID": "123123123",
    "CreatedAt": "2014-01-15T16:09:19-05:00",
    "Status": "Active",
    "Name": "Welcome email",
    "Properties": {
      "From": "Hello <team@webapp123.com>",
      "ReplyTo": "mike@webapp123.com",
      "Subject": "Thanks for signing up to web app 123",
      "Content": {
          "Html": "...",
          "Text": "...",
          "EmailVariables": [
              "username",
              "user_id"
          ],
          "InlineCss": true
      },
      "TextPreviewUrl": "http://siteaddress.createsend.com/path/text/preview",
      "HtmlPreviewUrl": "http://siteaddress.createsend.com/path/html/preview"
    },
    "AddRecipientsToList": "62eaaa0338245ca68e5e93daa6f591e9"
}

Notes

  • If email content is managed in our Email Builder, the HTML property will read
    { Content: {"Html": "Content managed in Email Builder"} }
  • The AddRecipientsToList property corresponds to the ID of a subscriber list to which all recipients will be added, including CC/BCC. This setting can be overridden when sending a message.
Error responses:

Please see our response status codes for potential error responses to any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 926: Smart email not found No smart email with that ID could be found.
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Send a smart email

To deliver a smart email:

POST https://api.createsend.com/api/v3.1/transactional/smartEmail/{:smartEmailID}/send

smartEmailID The ID of the smart email to send

Expected body request:
{
    "To": [
        "Joe Smith <joesmith@example.com>",
        "jamesmith@example.com"
    ],
    "CC": null,
    "BCC": [
        "joesmith@example.com"
    ],
    "Attachments": [
        {
            "Content": "base64encoded",
            "Name": "Invoice.pdf",
            "Type": "application/pdf"
        }
    ],
    "Data": {
        "new_password_url": "https://mywebapp.com/newpwd?uid=jguf45h74gf",
        "username": "joesmith1"
    },
    "AddRecipientsToList": true
}

Data object, optional. Properties will be available in your email as variables which can be referenced using our Template Language. Read more about smart transactional email variables and how to use them in your email in our transactional support documentation.

AddRecipientsToList boolean, optional. Whether to add all recipients to the subscriber list specified in the Smart Email. False by default. You must have permission from the recipients before adding them to a subscriber list in order to send them marketing email.

Attachments object, optional. Specifies attachments to include with transactional email. Must include Base64 encoded content, a file name, and file type. All file types accepted.

Notes

  • You may send to a maximum of 25 recipients across To, CC, and BCC.
  • The response will be an array, with each recipient getting its own MessageID.
Expected response:
HTTP/1.1 202 Accepted

[
    {
      "Status": "Accepted",
      "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
      "Recipient": "Joe Smith <joesmith@example.com>"
    },
    ...
]
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 1: Invalid Recipient Address A valid recipient address is required.
  • 952: Recipient Required Recipient is required. At least one To, CC, or a BCC address is required
  • 953: Recipient too long Recipient name and email address have a maximum length of 250 characters
  • 953: Too many recipients {number} email addresses specified across To, Cc and Bcc. The limit is 25
  • 981: Attachment name is required Each attachment requires a name
  • 982: Attachment type is required Each attachment requires a mime type
  • 984: Invalid attachment content Attachment content is invalid, must be valid base64 encoded file.
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

If you receive a 401 Not Found response, the possible errors which may be included in the body are:

  • 926: Smart email not found Smart email not found

Send classic email

To send an email providing your own content:

POST https://api.createsend.com/api/v3.1/transactional/classicEmail/send?clientID={:clientId}

clientId string, optional. Note to agencies: if you are using an account API key or OAuth, this is required as you need to specify the client. This is not necessary if you use a client-specific API key.

Expected body request:
{
  "Subject": "Thanks for signing up to web app 123",
  "From": "Mike Smith <mike@webapp123.com>",
  "ReplyTo": "support@webapp123.com",
  "To": [
    "Joe Smith <joesmith@example.com>",
    "jamesmith@example.com"
  ],
  "CC": [
    "Joe Smith <joesmith@example.com>"
  ],
  "BCC": null,
  "Html": "",
  "Text": "",
  "Attachments": [
    {
      "Type": "application/pdf",
      "Name": "Invoice.pdf",
      "Content": "base64encoded"
    }
  ],
  "TrackOpens": true,
  "TrackClicks": true,
  "InlineCSS": true,
  "Group": "Password Reset",
  "AddRecipientsToListID": "62eaaa0338245ca68e5e93daa6f591e9"
}

Group string, optional. A name to use for grouping email for reporting. There is a limited number of groups, so this should not be unique or changed frequently.

Text string, optional. Text component of the email. If not provided, we'll auto-generate the text version from the HTML.

TrackOpens boolean. True by default.

TrackClicks boolean. True by default.

InlineCSS boolean. Moves any CSS inline to improve compatibility with email clients. True by default.

Attachments object, optional. Specifies attachments to include with transactional email. Must include Base64 encoded content, a file name, and file type. All file types accepted.

AddRecipientToListID id, optional. The ID of a subscriber list to add all recipients to, including CC/BCC. You must have permission from your recipients before adding them to a subscriber list to send them marketing email.

Notes

  • You may send to a maximum of 25 recipients across To, CC, and BCC.
  • The response will be an array, with each recipient getting its own MessageID.
Expected response:
HTTP/1.1 202 Accepted

[
  {
    "Status": "Accepted",
    "Recipient": "Joe Smith <joesmith@example.com>",
    "MessageID": "549f114b-aa76-11e4-8b24-2fa9fbbe36ff"
  },
  ...
]
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 1: Invalid Recipient Address A valid recipient address is required.
  • 952: Recipient is Required At least one To, CC, or a BCC address is required
  • 953: Long Recipient details Recipient name and email address have a maximum length of 250 characters
  • 954: Too many recipients {number} email addresses specified across To, Cc and Bcc. The limit is 25
  • 955: Invalid Reply-To address Must be a valid email address.
  • 957: From Required A valid email address is required.
  • 958: Long From details From name and email address have a maximum length of 250 characters
  • 960: Content is required Either "HTML" or "Text" content must be specified.
  • 970: TrackClicks parameter invalid Must be "true" or "false".
  • 971: TrackOpens parameter invalid Must be "true" or "false".
  • 972: InlineCSS parameter invalid Must be "true" or "false".
  • 981: Attachment name is required Each attachment required a name.
  • 982: Attachment type is required Each attachment requires a mime type.
  • 984: Invalid attachment content Attachment content is invalid, must be a valid base64 encoded file.
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Classic email group listing

To get a list of classic email groups:

GET https://api.createsend.com/api/v3.1/transactional/classicEmail/groups?clientID={:clientID}

clientID string, optional. Note to agencies: if you are using an account API key or OAuth, this is required as you need to specify the client. This is not necessary if you use a client-specific API key.

Expected response:
[
    {
        "Group": "Welcome email",
        "CreatedAt": "2014-01-15T16:09:19-05:00"
    },
    ...
]

Statistics

To get delivery and engagement statistics, optionally filter by smart email or classic group:

GET https://api.createsend.com/api/v3.1/transactional/statistics?group={:Group}&from={:from}&to={:to}&timezone={:timezone}&clientID={:clientID}

clientID string, optional. Note to agencies: if you are using an account API key or OAuth, this is required as you need to specify the client. This is not necessary if you use a client-specific API key.
smartEmailID guid, optional. Filter results to Smart Email by supplying a smart email ID.
group string, optional. Filter results by Group by supplying a URL-encoded classic group name.
from iso-8601 date in the format YYYY-MM-DD, optional. Default: 29 days ago.
top iso-8601 date in the format YYYY-MM-DD, optional. Default: Today.
timezone string, optional. Values can be utc or client. Default: client’s time zone. When requesting statistics for a specific period of time, you can choose to define that period using either your local time zone or UTC.

Expected response:
{
    "Query": {
      "Group": "Password Reset",
      "SmartEmailID": "fc123352-35a4-11e5-8538-6c4008bc7468",
      "From": "2014-02-03",
      "To": "2015-02-02",
      "TimeZone": "(GMT+10:00) Canberra, Melbourne, Sydney"
    },
    "Sent": 1000,
    "Bounces": 8,
    "Delivered": 992,
    "Opened": 300,
    "Clicked": 50
}
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 920: Invalid from date The date must be provided in the format YYYY-MM-DD
  • 921: Invalid from date "From Date" must be before or equal to "To Date"
  • 922: Invalid to date The date must be provided in the format YYYY-MM-DD
  • 923: Invalid Timezone Timezone must be "utc" or "client"
  • 924: Conflict between Group and Smart Email ID You may only supply one of Group or Smart Email ID
  • 925: Invalid Smart mail ID Value must be a valid GUID.
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Message timeline

To get a list of sent messages (classic or smart) filtered by group, email date and more, do the following:

GET https://api.createsend.com/api/v3.1/transactional/messages?group={:group}&sentBeforeID={:sentBeforeID}&sentAfterID={:sentAfterID}&count={:count}&status={delivered|bounced|spam|all}&clientID={:clientID}

status string, optional. Filter messages by status. Default: all.
count integer, optional. Maximum number of results to return in a single request. Default: 50, maximum: 200.
sentBeforeID guid, optional. A messageID used for pagination, returns emails sent before the specified message. Default: null.
sentAfterID guid, optional. A messageID used for pagination, returns emails sent after the specified message. Default: null.
smartEmailID guid, optional. A smart email ID to filter by.
group string, optional. A url-encoded classic group name to filter by.
clientID string, optional. Note to agencies: if you are using an account API key or OAuth, this is required as you need to specify the client. This is not necessary if you use a client-specific API key.

This will return the details of the message, including an ID which can be queried for status.

Expected response:
HTTP/1.1 200 OK
X-Total-Count: 321

[
  {
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Delivered",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <joesmith@example.com>",
    "From": "Team <team@company.com>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true
  },
  {
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Delivered",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <joesmith@example.com>",
    "From": "Team <team@company.com>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true,
    "Group": "Password Reset",
  },
  {
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Delivered",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <joesmith@example.com>",
    "From": "Team <team@company.com>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true,
    "SmartEmailID": "123123123123"
  },
  ...
]

Notes

If the message was sent as a classic email:

  • Message content (HTML, Text) is only returned for 30 days after sending.
  • No SmartEmailID property will be included in the response.
  • Grouped email will instead have a Group property with the group name.
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 404: Not Found Send ID not found
  • 850: Invalid count Must be a number between 1 and 200.
  • 904: Invalid sentbeforeid Value must be a valid GUID.
  • 905: Invalid sentafterid Value must be a valid GUID.
  • 925: Invalid smartEmailID Value must be a valid GUID.
  • 932: Invalid status Must be one of "bounced", "delivered", "spam", or "all"
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Message details

To get the message details, no matter how it was sent, including status:

GET https://api.createsend.com/api/v3.1/transactional/messages/{:messageID}?statistics={:statistics}

messageID string, required. ID of the message.
statistics boolean, optional. Whether to include detailed opens/clicks. Defaults to false.

Expected response:
{
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Delivered",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "SmartEmailID": "c0da9c4c-e7e4-11e4-a74d-6c4008bc7468",
    "CanBeResent": true,
    "Recipient": "Joe Smith <joesmith@example.com>",
    "Message": {
        "From": "Team Webapp <team@webapp123.com>",
        "Subject": "Thanks for signing up to web app 123",
        "To": [
          "Joe Smith <joesmith@example.com>",
          "jamesmith@example.com"
        ],
        "CC": [
          "Joe Smith <joesmith@example.com>"
        ],
        "BCC": "joesmith@example.com",
	 "ReplyTo": "support@webapp123.com",
        "Attachments": [
            {
                "Name": "Invoice.pdf",
                "Type": "application/pdf"
            }
        ],
        "Body": {
            "Html": "...",
            "Text": "..."
        },
        "Data": {
            "new_password_url": "https://mywebapp.com/newpwd?uid=jguf45h74g"
        }
    },
    "TotalOpens": 2,
    "TotalClicks": 4,
    "Opens": [
        {
            "EmailAddress": "jamesmith@example.com",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1",
            "Geolocation": {
                "Latitude": -33.8683,
                "Longitude": 151.2086,
                "City": "Sydney",
                "Region": "New South Wales",
                "CountryCode": "AU",
                "CountryName": "Australia"
            },
            "MailClient": {
                "Name": "Apple Mail",
                "Version": "Apple Mail 8"
            }
        },
        ...
    ],
    "Clicks": [
        {
            "EmailAddress": "jamesmith@example.com",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1",
            "URL": "http://www.myexammple.com/index.html",
            "Geolocation": {
              "Latitude": -33.8683,
              "Longitude": 151.2086,
              "City": "Sydney",
              "Region": "New South Wales",
              "CountryCode": "AU",
              "CountryName": "Australia"
            }
        },
        ...
    ]
}

Notes

If the message was sent as a classic email:

  • Message content (HTML, Text) is only returned for 30 days after sending.
  • No SmartEmailID property will be included in the response.
  • Grouped email will instead have a Group property with the group name.
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 302: Invalid Message ID Message ID not found
  • 935: Invalid statistics parameter Value must be 'true' or 'false'
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Resend message

To resend a message:

POST https://api.createsend.com/api/v3.1/transactional/messages/{:messageID}/resend

messageID string, required. ID of the message.

Notes

  • The MessageID in the response will be a new MessageID for the resent message, which you can query for status.
Expected response:
HTTP/1.1 202 Accepted

{
    "Status": "Accepted",
    "Recipient": "Joe Smith <joesmith@example.com>",
    "MessageID": "cfb5e081-ef66-4bc4-a1c0-48493b34e694"
}
Error responses:

Please see our response status codes for details of potential error responses for any API request.

If you receive a 400 Bad Request response, the possible errors which may be included in the body are:

  • 302: Invalid Message ID Message ID not found
  • 410: Gone Original message can not be resent because it contained attachments or the content is no longer available.
  • 993: You need to set up custom authentication to send transactional emails. Update the settings in your account to manage your own authentication.
  • 994: Your sending domain must match your authenticated domain to send transactional email.

Join 200,000 companies around the world that use Campaign Monitor to run email marketing campaigns that deliver results for their business.

Get started for free