Email Marketing API

Our Email API supports sending Email messages for Business. The API can handle single or large number of marketing messages.

Marketing API is used to send bulk marketing emails. This API is specifically designed to send marketing emails which require some operations such as adding unsubscribe link or processing unsubscribe feedback.

Permissions Required

To access Marketing Email API endpoints, the user must have a valid product token associated with their account.

Fact Sheet

Feature	Support	Remark
Text Messages	Yes	The maximum length of the message must be less than 25 MB including media and must be UTF-8 encoded message
Media	Yes	File Name should end with proper extension. Multiple media files are allowed per message and must be base64 encoded. The size of the media files including the message content should not exceed 25MB.
Media: images	Yes	Maximum size should be less than 25 MB including other attachments and text content.
Media: Audio	No	Audio files are not supported as of now.
Media: Video	No	Video files are not supported as of now.
Media: Documents	Yes	Maximum size should be less than 25 MB including other attachments and text content.
HTML content	Yes	Maximum size of the content should be less than 25MB including other attachments and text content.
Text content	Yes	Maximum size of the content should be less than 25MB including other attachments and text content.
CC	Yes	Maximum number of CCs including To and BCC should be less than 50.
BCC	Yes	Maximum number of BCCs including To and BCC should be less than 50.
To	Yes	Maximum number of Tos including To and BCC should be less than 50.
Unsubscribe Link	Yes	Automatically added or use placeholder

Managing Marketing Emails

The Marketing Email API uses product tokens to authenticate requests and automatically handles unsubscribe compliance for all marketing campaigns. Each email is processed through validation services to ensure deliverability and compliance.

Sending Emails

Send Marketing emails with automatic unsubscribe link inclusion.

Required Header X-CM-PRODUCTTOKEN

POST /v1/marketing
Content-Type: application/json
X-CM-PRODUCTTOKEN: {your-product-token}

Request Headers

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

Request Body Example

The example below shows the simplest 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": 0,
  "details": "Email sent successfully",
  "messageId": "550e8400-e29b-41d4-a716-446655440000"
}

Error Responses

Invalid Product Token (401)

{
  "errorCode": 3,
  "details": "Product token is mandatory.",
  "messageId": ""
}

Invalid Request (400)

{
  "errorCode": 1,
  "details": "From Address is invalid or empty",
  "messageId": ""
}

Email Too Large (403)

{
  "errorCode": 2,
  "details": "Email size exceeds maximum allowed size",
  "messageId": ""
}

Internal Server Error (500)

{
  "errorCode": 4,
  "details": "Internal server error occurred",
  "messageId": ""
}

Request Parameters

Request Body Fields

Field	Type	Required	Description
fromAddress	string	Yes	Sender's email address
fromName	string	No	Sender's display name
replyToAddress	string	No	Reply-to email address
replyToName	string	No	Reply-to display name
toAddresses	array	Yes	List of primary recipients
ccs	array	No	List of CC recipients
bccs	array	No	List of BCC recipients
subject	string	Yes	Email subject line
htmlBody	string	Yes	HTML email content
textBody	string	Yes	Plain text email content
attachments	array	No	List of file attachments
customerReference	string	No	Your reference for tracking

Recipient Object (toAddresses)

Field	Type	Required	Description
toAddress	string	Yes	Recipient email address
toName	string	Yes	Recipient display name

CC/BCC Object

Field	Type	Required	Description
emailAddress	string	Yes	Recipient email address

Attachment Object

Field	Type	Required	Description
fileName	string	Yes	Name of the file with extension
data	string	Yes	Base64 encoded file content
contentType	string	Yes	MIME type of the file
contentId	string	No	Content ID for inline images

Custom Unsubscribe Link

The Email Gateway automatically includes a standard unsubscribe link at the end of all marketing emails. However, you can customize the placement using the {{{unsubscribe_link}}} placeholder:

<p>If you no longer wish to receive these emails, 
<a href="{{{unsubscribe_link}}}">click here to unsubscribe</a>.</p>

When the email is sent, the system will replace the placeholder with the recipient's unique unsubscribe link. If the placeholder is not included, the system will append the default unsubscribe link to the end of your email content to ensure compliance with email marketing regulations.

By using the {{{unsubscribe_link}}} placeholder, you can control exactly where the unsubscribe link appears in your email, giving you more flexibility in designing your email content.

Supported File Types

Category	Extensions	Max Size
Images	.jpg, .jpeg, .png	25 MB
Documents	.pdf, .doc, .docx	25 MB
Archives	.zip	25 MB

Status Codes

Status Code	Description
200	OK: Email sent successfully
400	Bad Request: Invalid request data
401	Unauthorized: Invalid product token
403	Forbidden: Email rejected (size/content)
500	Internal Server Error: Server-side error

Error Handling

All error responses follow a consistent format:

{
  "errorCode": 1,
  "details": "Error description",
  "messageId": ""
}

Best Practices

Unsubscribe Compliance: Always include unsubscribe functionality for marketing emails
Content Size: Keep total email size under 25MB including all attachments
Recipient Validation: Ensure all email addresses are properly formatted
File Types: Only use supported file types for attachments
Authentication: Securely store and rotate product tokens

Example Use Cases

Newsletter Campaign

Monitor when open rates exceed expectations:

{
  "fromAddress": "[email protected]",
  "fromName": "Company Newsletter",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "John Subscriber"
    }
  ],
  "subject": "Weekly Newsletter - Special Offers Inside!",
  "htmlBody": "<h1>This Week's Deals</h1><p>Check out our latest offers...</p><p><a href=\"{{{unsubscribe_link}}}\">Unsubscribe</a></p>",
  "textBody": "This Week's Deals - Check out our latest offers...",
  "customerReference": "newsletter-week-42"
}

Product Launch Announcement

Launch announcement with product images:

{
  "fromAddress": "[email protected]",
  "fromName": "Company Marketing",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Valued Customer"
    }
  ],
  "subject": "Introducing Our New Product Line!",
  "htmlBody": "<h1>New Product Launch</h1><p>We're excited to announce...</p><img src=\"cid:product_image\"/>",
  "textBody": "New Product Launch - We're excited to announce...",
  "attachments": [
    {
      "fileName": "product_catalog.pdf",
      "data": "JVBERi0xLjQKJcfsj6eUKCAg...",
      "contentType": "application/pdf"
    },
    {
      "fileName": "product_image.jpg",
      "data": "/9j/4AAQSkZJRgABAQEAYABgAAD...",
      "contentType": "image/jpeg",
      "contentId": "product_image"
    }
  ],
  "customerReference": "product-launch-2024"
}

Promotional Campaign with Multiple Recipients

Campaign with CC for tracking:

{
  "fromAddress": "[email protected]",
  "fromName": "Store Promotions",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Customer One"
    },
    {
      "toAddress": "[email protected]",
      "toName": "Customer Two"
    }
  ],
  "ccs": [
    {
      "emailAddress": "[email protected]"
    }
  ],
  "subject": "Flash Sale - 50% Off Everything!",
  "htmlBody": "<h1>Flash Sale Alert!</h1><p>Everything in our store is 50% off for the next 24 hours!</p><p>Use code: FLASH50</p>",
  "textBody": "Flash Sale Alert! Everything in our store is 50% off for the next 24 hours! Use code: FLASH50",
  "customerReference": "flash-sale-march-2024"
}