Our API

The Campaign Monitor API opens up a world of possibilities for integrating our platform with your favorite CMS, blog, or other third party software.

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

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

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

  • 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 documentation for details of potential error responses for any API request.

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

  • 932: Invalid status parameter Must be one of "all", "active", or "draft" for Smart Email Listing Endpoint or "bounced", "delivered", "spam", or "all" for Message Timeline Endpoint.
  • 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

Get https://api.createsend.com/api/v3.3/transactional/smartEmail/{:smartEmailID}

To get the details for a smart transactional email:

  • SMARTEMAILID The ID of the smart email to send
Expected response: 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "SmartEmailID": "c475db61-665e-11eb-b2b7-51b1f4471faa",
    "CreatedAt": "2014-01-15T16:09:19-05:00",
    "Status": "Active",
    "Name": "Welcome email",
    "Properties": {
        "From": "Hello <[email protected]>",
        "ReplyTo": "[email protected]",
        "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 documentation for details of potential error responses for any API request.

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

  • 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

Post https://api.createsend.com/api/v3.3/transactional/smartEmail/{:smartEmailID}/send

To deliver a smart email:

  • SMARTEMAILID The ID of the smart email to send
Expected request: 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "To": [
        "Joe Smith <[email protected]>",
        "[email protected]"
    ],
    "CC": null,
    "BCC": [
        "[email protected]"
    ],
    "Attachments": [
        {
            "Content": "base64encoded",
            "Name": "Invoice.pdf",
            "Type": "application\/pdf"
        }
    ],
    "Data": {
        "new_password_url": "https://mywebapp.com/newpwd?uid=jguf45h74gf",
        "username": "joesmith1"
    },
    "AddRecipientsToList": true,
    "ConsentToTrack": "Yes"
}
  • 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.
  • ConsentToTrack string. This value applies to all recipients (To, CC, and BCC) of the email, as well as any subscribers with the same email address across all lists within a client. If an email address has no value stored for ConsentToTrack, it is assumed that the subscriber has given consent.
    • Yes Tracking is permitted for this email address
    • No Tracking is not permitted for this email address
    • Unchanged Do not change the current email address tracking preference

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 <[email protected]>"
    },
    ...
]
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 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
  • 974: Consent to track value is invalid or not provided
  • 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.
  • 996: Data field is too large. The maximum size is 100 KB.

If you receive a 401 Not Found 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.

Send classic email

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

To send an email providing your own content:

  • 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 request: 
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "Subject": "Thanks for signing up to web app 123",
  "From": "Mike Smith <[email protected]>",
  "ReplyTo": "[email protected]",
  "To": [
    "Joe Smith <[email protected]>",
    "[email protected]"
  ],
  "CC": [
    "Joe Smith <[email protected]>"
  ],
  "BCC": null,
  "Html": "",
  "Text": "",
  "Attachments": [
    {
      "Type": "application/pdf",
      "Name": "Invoice.pdf",
      "Content": "base64encoded"
    }
  ],
  "TrackOpens": true,
  "TrackClicks": true,
  "InlineCSS": true,
  "Group": "Password Reset",
  "AddRecipientsToListID": "62eaaa0338245ca68e5e93daa6f591e9",
  "ConsentToTrack": "Yes"
}
  • 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.
  • ConsentToTrack string. This value applies to all recipients (To, CC, and BCC) of the email, as well as any subscribers with the same email address across all lists within a client. If an email address has no value stored for ConsentToTrack, it is assumed that the subscriber has given consent.
    • Yes Tracking is permitted for this email address
    • No Tracking is not permitted for this email address
    • Unchanged Do not change the current email address tracking preference

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 <[email protected]>",
    "MessageID": "549f114b-aa76-11e4-8b24-2fa9fbbe36ff"
  },
  ...
]
Error responses:

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

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

  • 1: Invalid Email Address Email address is missing or incorrectly formatted.
  • 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
  • 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".
  • 974: Consent to track value is invalid or not provided
  • 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.

Classic email group listing

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

To get a list of classic email groups:

  • 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

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

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

  • 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.
  • TO 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}

Notes

Sent is the number of emails that were successfully sent from our platform.

Delivered is the number of emails that were successfully received by the recipient’s email provider.

 

Error responses:

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

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

  • 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 smartEmailID 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

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

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

  • 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": "Sent",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <[email protected]>",
    "From": "Team <[email protected]>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true
  },
  {
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Sent",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <[email protected]>",
    "From": "Team <[email protected]>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true,
    "Group": "Password Reset",
  },
  {
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Sent",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "Recipient": "Joe Smith <[email protected]>",
    "From": "Team <[email protected]>",
    "Subject": "Your password has been reset",
    "TotalOpens": 2,
    "TotalClicks": 4,
    "CanBeResent": true,
    "SmartEmailID": "123123123123"
  },
  {
    "MessageID": "372475e4-603b-11eb-abf3-e62b3bba4716",
    "Group": "",
    "SentAt": "2014-01-14T16:08:00-05:00",
    "Status": "Bounced",
    "BounceType": "SBMF",
    "BounceCategory": "Soft",
    "Recipient": "Joe Smith <[email protected]>",
    "From": "Team <[email protected]>",
    "Subject": "Your password has been reset",
    "TotalOpens": 0,
    "TotalClicks": 0,
    "CanBeResent": true
   },
  ...
]

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.

Status field in the response can have one of the following values:

Received
Queued
Sent
Paused
Processed
RateLimited
BadRequest
Error
NotFound
Bounced
Spam
Accepted

If an email was bounced, the corresponding timeline entry will include BounceType and BounceCategory fields.

BounceType response field values:

Soft
Hard

BounceCategory response field definitions:

NB (NON BOUNCE
HB (HARD BOUNCE)
SB (SOFT BOUNCE - General)
SBDF (SOFT BOUNCE - Dns Failure)
SBMF (SOFT BOUNCE - Mailbox Full)
SBMS (SOFT BOUNCE - Message Size Too Large)
GB (GENERAL BOUNCE)
BN (BOUNCE WITH NO EMAIL ADDRESS)
MB (MAIL BLOCK - General)
MBKS (MAIL BLOCK - Known Spammer)
MBSD (MAIL BLOCK - Spam Detected)
MBAD (MAIL BLOCK - Attachment Detected)
MBRD (MAIL BLOCK - Relay Denied)
AR (AUTO REPLY)
TB (TRANSIENT BOUNCE)
SR (SUBSCRIBE REQUEST)
UR (UNSUBSCRIBE REQUEST)
CR (CHALLENGE RESPONSE)

 

Error responses:

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

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

  • 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 parameter Must be one of "all", "active", or "draft" for Smart Email Listing Endpoint or "bounced", "delivered", "spam", or "all" for Message Timeline Endpoint.
  • 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

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

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

  • MESSAGEID string, required. ID of the message.
  • STATISTICS boolean, optional. Whether to include detailed opens/clicks. Defaults to false.
  • EXCLUDEMESSAGEBODY boolean, optional. Whether to exclude message body (Text/HTML) from the response. Defaults to false.
Expected response: 
{
    "MessageID": "ddc697c7-0788-4df3-a71a-a7cb935f00bd",
    "Status": "Sent",
    "SentAt": "2014-01-15T16:09:19-05:00",
    "SmartEmailID": "c0da9c4c-e7e4-11e4-a74d-6c4008bc7468",
    "CanBeResent": true,
    "Recipient": "Joe Smith <[email protected]>",
    "Message": {
        "From": "Team Webapp <[email protected]>",
        "Subject": "Thanks for signing up to web app 123",
        "To": [
          "Joe Smith <[email protected]>",
          "[email protected]"
        ],
        "CC": [
          "Joe Smith <[email protected]>"
        ],
        "BCC": "[email protected]",
     "ReplyTo": "[email protected]",
        "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": "[email protected]",
            "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": "[email protected]",
            "Date": "2009-05-18 16:45:00",
            "IPAddress": "192.168.0.1",
            "URL": "https://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

Status field in the response can have one of the following values:

Received
Queued
Sent
Paused
Processed
RateLimited
BadRequest
Error
NotFound
Bounced
Spam
Accepted

If an email was bounced, the response will include BounceType and BounceCategory fields.

BounceType response field values:

Soft
Hard

BounceCategory response field definitions:

NB (NON BOUNCE
HB (HARD BOUNCE)
SB (SOFT BOUNCE - General)
SBDF (SOFT BOUNCE - Dns Failure)
SBMF (SOFT BOUNCE - Mailbox Full)
SBMS (SOFT BOUNCE - Message Size Too Large)
GB (GENERAL BOUNCE)
BN (BOUNCE WITH NO EMAIL ADDRESS)
MB (MAIL BLOCK - General)
MBKS (MAIL BLOCK - Known Spammer)
MBSD (MAIL BLOCK - Spam Detected)
MBAD (MAIL BLOCK - Attachment Detected)
MBRD (MAIL BLOCK - Relay Denied)
AR (AUTO REPLY)
TB (TRANSIENT BOUNCE)
SR (SUBSCRIBE REQUEST)
UR (UNSUBSCRIBE REQUEST)
CR (CHALLENGE RESPONSE)
Error responses:

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

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

  • 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

Post https://api.createsend.com/api/v3.3/transactional/messages/{:messageID}/resend

To resend a message:

  • 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 <[email protected]>",
    "MessageID": "cfb5e081-ef66-4bc4-a1c0-48493b34e694"
}
Error responses:

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

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

  • 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.