The Transactional Email API is designed for sending event-driven emails that require immediate delivery. These emails are typically triggered by user actions or system events, such as sign-ups, purchase confirmations, or password recovery requests.

If you're looking to send bulk promotional emails or newsletters, please use the Marketing Email API documentation.

Authentication

To interact with the Transactional Email API, you need a secret key called the Product Token. Once you have access to the Email App, you can retrieve the Product Token by navigating to the Settings page within the app and copying the token.

When making a request to the Transactional Email API, include the Product Token in the request headers. Specifically, add it as a header with the key name X-CM-PRODUCTTOKEN in your POST request.

Request Headers

POST https://api.cm.com/email/gateway/v1/transactional?priority={priority}
Content-Type: application/json
X-CM-PRODUCTTOKEN: {your-product-token}

Header Name	Type	Required	Description
X-CM-PRODUCTTOKEN	string	Yes	Valid product token GUID
Content-Type	string	Yes	Must be "application/json"

The Transactional Email API also expects a priority value in the query parameter which can either be Low or High.

Parameter	Type	Required	Description
priority	string	Yes	"low" or "high"

Request Example

The example provided below demonstrates the most basic structure of an Email message request.

{
  "fromAddress": "[email protected]",
  "fromName": "Samuel",
  "replyToAddress": "",
  "replyToName": "",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Robert Vadra"
    }
  ],
  "ccs": [
    {
      "emailAddress": "[email protected]"
    }
  ],
  "bccs": [
    {
      "emailAddress": "[email protected]"
    }
  ],
  "subject": "An example test email",
  "htmlBody": "<p>Just a test email</p><img src=\"cid:cat_image\"/>",
  "textBody": "",
  "attachments": [
    {
      "fileName": "cat.jpeg",
      "data": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/2wBDAQkJCQwLDBgNDRgyIRwhMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjL/wAARCAABAAEDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD3+iiigD//2Q==",
      "contentType": "image/jpeg",
      "contentId": "cat_image"
    }
  ],
  "customerReference":""
}

Successful Response

{
  "errorCode": 202,
  "details": "Email sent successfully",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

For all response codes see the response codes page.

Test Your Integration

If you want to test your integration or see how quickly you can send multiple messages through the Email Gateway without affecting your reputation, you can use the Email Gateway' Sandbox or Integration mode.

Sandbox Mode: Verify and validate your integration and requests without sending messages.
Integration Mode: Tests the complete workflow and speed without sending messages.