Breaking Changes for Email Gateway

🚧

To further enhance clarity and consistency across our platform, we’re also updating the structure of the email request body. The new format introduces a more standardized and intuitive naming structure. Please ensure your implementation is updated to align with the new request body format before the effective date.

Effective Date: October 27, 00:00 CET

Documentation will be updated to reflect the new structure on October 27.

Breaking Changes

The Email Gateway API has been completely redesigned with a new request/response structure. This is a breaking change that requires updates to all client implementations.

New Request Structure

The API now uses a simplified and more consistent structure:

{
  "from": {
    "email": "[email protected]",
    "name": "Sender Name"
  },
  "replyTo": {
    "email": "[email protected]", 
    "name": "Reply Name"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Recipient Name"
    }
  ],
  "cc": [
    {
      "email": "[email protected]",
      "name": "CC Name"
    }
  ],
  "bcc": [
    {
      "email": "[email protected]", 
      "name": "BCC Name"
    }
  ],
  "subject": "Email Subject",
  "html": "<p>HTML content (optional)</p>",
  "text": "Plain text content (optional)",
  "attachments": [
    {
      "fileName": "document.pdf",
      "content": "base64-encoded-content",
      "contentType": "application/pdf",
      "contentId": "attachment-id"
    }
  ],
  "customerReference": "your-reference"
}

New Response Structure

The API now returns a consistent response format:

{
  "status": 202,
  "message": "Success",
  "success": true,
  "messageId": "unique-message-id"
}

Key Breaking Changes

1. Email Address Structure

All email fields now use a consistent object structure:

// Old format
"fromAddress": "[email protected]",
"fromName": "Sender Name"

// New format
"from": {
  "email": "[email protected]", 
  "name": "Sender Name"
}

2. Field Name Changes

3. Required Fields

• from: Required - must include valid email and name
• to: Required - at least one recipient must be provided
• subject: Required
• html OR text: At least one content field is required (not both mandatory)
• replyTo: Optional - defaults to from if not provided

4. Response Format

• Responses are now with consistent object structure

{
  "status": integer,
  "message": "string",
  "success": boolean,
  "messageId": "unique-message-id"
}

• Status codes are included in the response body as status field
• Success indicator included as success boolean field

Migration Guide

Step 1: Update Request Structure

Transform your existing request payload:

// Old request
const oldRequest = {
  fromAddress: "[email protected]",
  fromName: "Sender Name", 
  toAddresses: [
    { toAddress: "[email protected]", toName: "Recipient Name" }
  ],
  htmlBody: "<p>Content</p>",
  textBody: "Content"
};

// New request
const newRequest = {
  from: {
    email: "[email protected]",
    name: "Sender Name"
  },
  to: [
    { email: "[email protected]", name: "Recipient Name" }
  ],
  html: "<p>Content</p>",
  text: "Content"
};

Step 2: Update Response Handling

// Old response handling
if (response.errorCode === 0) {
  console.log("Success:", response.details);
}

// New response handling  
if (response.success) {
  console.log("Success:", response.message);
  console.log("Message ID:", response.messageId);
}

Step 3: Update Validation Logic

• Ensure either html OR text is provided (not both required)
• All email objects must have both email and name properties
• replyTo is now optional

Endpoints

• Marketing Emails: POST /v1/marketing
• Transactional Emails: POST /v1/transactional?priority={low|high}

Headers

• X-CM-PRODUCTTOKEN: Required - Your product authentication token
• Sandbox-Mode: Optional - Set to true for testing (default: false)

Status Codes

• 202 - Email accepted for processing
• 200 - Sandbox mode (email accepted but not sent)
• 400 - Bad request (validation errors)
• 401 - Unauthorized (invalid/missing product token)
• 500 - Internal server error