Email Transactional API

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

Transactional API is used for sending transactional emails. In transactional emails you have to provide priority value which informs Gateway API whether the request is high priority request or low priority request.

Fact Sheet

Feature	Support	Remark
Priority Levels	Yes	Low and High priority support
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.

Sending Emails

Email API uses from (fromAddress) and to (toAddresses) email address for sending Emails. The API also requires logical account of the consumer. The API also expects a priority value which can either be Low or High.

Required Header X-CM-PRODUCTTOKEN

POST /v1/transactional?priority={priority}
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"

Query Parameters

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

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 Priority (400)

{
  "errorCode": 1,
  "details": "Priority must be 'low' or 'high'.",
  "messageId": ""
}

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": ""
}

Recipients Limit Exceeded (400)

{
  "errorCode": 1,
  "details": "Recipients count exceeds the max allowed limit of 50",
  "messageId": ""
}

Internal Server Error (500)

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

Request Parameters

Query Parameters

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

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

Priority Levels

Priority	Description	Use Cases
high	Time-sensitive, critical emails	Password resets, OTP, urgent alerts
low	Standard transactional emails	Order confirmations, receipts

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

Priority Usage: Use "high" priority only for truly time-sensitive emails
Clear Subject Lines: Make subjects descriptive and actionable
Customer References: Use meaningful reference IDs for tracking and debugging
Content Size: Keep total email size under 25MB including all attachments
Recipient Validation: Ensure all email addresses are properly formatted

Example Use Cases

Order Confirmation (Low Priority)

Standard order confirmation with receipt:

{
  "fromAddress": "[email protected]",
  "fromName": "Shop Orders",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "John Customer"
    }
  ],
  "subject": "Your Order #12345 Has Been Confirmed",
  "htmlBody": "<h1>Order Confirmed</h1><p>Thank you for your purchase. Your order #12345 has been confirmed and will be processed within 1-2 business days.</p>",
  "textBody": "Order Confirmed - Thank you for your purchase. Your order #12345 has been confirmed and will be processed within 1-2 business days.",
  "attachments": [
    {
      "fileName": "order_receipt.pdf",
      "data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PAovVHlwZSAv...",
      "contentType": "application/pdf"
    }
  ],
  "customerReference": "order-12345"
}

Password Reset (High Priority)

Time-sensitive password reset email:

{
  "fromAddress": "[email protected]",
  "fromName": "App Security",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "App User"
    }
  ],
  "subject": "Password Reset Request - Action Required",
  "htmlBody": "<h1>Reset Your Password</h1><p>Click the link below to reset your password:</p><a href=\"https://app.com/reset?token=abc123xyz\" style=\"background: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;\">Reset Password</a><p>This link expires in 24 hours.</p><p>If you didn't request this, please ignore this email.</p>",
  "textBody": "Reset Your Password - Click the link below to reset your password: https://app.com/reset?token=abc123xyz. This link expires in 24 hours. If you didn't request this, please ignore this email.",
  "customerReference": "pwd-reset-abc123xyz"
}

Account Verification (High Priority)

Critical account verification email:

{
  "fromAddress": "[email protected]",
  "fromName": "Platform Verification",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "New User"
    }
  ],
  "subject": "Verify Your Account - Welcome to Platform!",
  "htmlBody": "<h1>Welcome to Platform!</h1><p>Please verify your email address by clicking the button below:</p><a href=\"https://platform.com/verify?code=xyz789\" style=\"background: #28a745; color: white; padding: 12px 24px; text-decoration: none; border-radius: 5px; display: inline-block;\">Verify Email</a><p>This verification link expires in 48 hours.</p>",
  "textBody": "Welcome to Platform! Please verify your email address by visiting: https://platform.com/verify?code=xyz789. This verification link expires in 48 hours.",
  "customerReference": "verification-xyz789"
}

Invoice Delivery (Low Priority)

Business invoice with accounting CC:

{
  "fromAddress": "[email protected]",
  "fromName": "Company Billing",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Business Client"
    }
  ],
  "ccs": [
    {
      "emailAddress": "[email protected]"
    }
  ],
  "subject": "Invoice #INV-2024-001 - Payment Due in 30 Days",
  "htmlBody": "<h1>Invoice #INV-2024-001</h1><p>Please find your invoice attached. Payment is due within 30 days of the invoice date.</p><p>If you have any questions, please contact our billing department.</p>",
  "textBody": "Invoice #INV-2024-001 - Please find your invoice attached. Payment is due within 30 days of the invoice date. If you have any questions, please contact our billing department.",
  "attachments": [
    {
      "fileName": "invoice_INV-2024-001.pdf",
      "data": "JVBERi0xLjQKJcfsj6eUKCAg...",
      "contentType": "application/pdf"
    }
  ],
  "customerReference": "invoice-INV-2024-001"
}

Two-Factor Authentication (High Priority)

Security code delivery:

{
  "fromAddress": "[email protected]",
  "fromName": "Bank Security",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Bank Customer"
    }
  ],
  "subject": "Your Security Code - Do Not Share",
  "htmlBody": "<h1>Security Code</h1><p>Your security code is: <strong style=\"font-size: 24px; color: #007bff;\">123456</strong></p><p>This code expires in 10 minutes.</p><p><strong>Never share this code with anyone.</strong></p>",
  "textBody": "Your security code is: 123456. This code expires in 10 minutes. Never share this code with anyone.",
  "customerReference": "2fa-code-123456"
}

Shipping Notification (Low Priority)

Order shipped notification with tracking

{
  "fromAddress": "[email protected]",
  "fromName": "Store Shipping",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "Valued Customer"
    }
  ],
  "subject": "Your Order #12345 Has Shipped!",
  "htmlBody": "<h1>Your Order Has Shipped!</h1><p>Great news! Your order #12345 has been shipped and is on its way.</p><p><strong>Tracking Number:</strong> 1Z999AA1234567890</p><p>You can track your package at: <a href=\"https://tracking.example.com/1Z999AA1234567890\">Track Package</a></p>",
  "textBody": "Your Order Has Shipped! Great news! Your order #12345 has been shipped and is on its way. Tracking Number: 1Z999AA1234567890. You can track your package at: https://tracking.example.com/1Z999AA1234567890",
  "customerReference": "shipment-12345"
}