Guides

Test Your Integration

Suggest Edits

We understand the importance of testing your integration in a secure and controlled environment. That’s why we offer two testing options: Sandbox Mode and Integration Mode. These features allow you to validate your workflow and test your integration without impacting real users or your domain reputation. Below, we’ll guide you through each mode and how to use them effectively.

ℹ️

Both the Transactional Email API and the Marketing Email API offer Sandbox and Integration mode, providing a safe and controlled environment for testing your integration.

Sandbox Mode

Sandbox Mode is designed for validating the integrity of your email requests without sending any emails. This mode ensures that your request meets service requirements before it’s processed for delivery. When Sandbox Mode is enabled, our system performs the following checks:

  • Data Validation: Ensures all required fields are present and correctly formatted.
  • Email Size Verification: Confirms that the email size is within acceptable limits.
  • Attachment Validation: Checks that attachments meet our requirements.
  • Message Format Compliance: Validates the structure of your email content.

To enable Sandbox Mode, include the header "Sandbox-Mode: true" in your API request. When enabled, our service validates your request without delivering messages to recipients. Default value for Sandbox-Mode header is false.

Example Request

Here’s an example of a request in Sandbox Mode:

curl -X POST "https://api.cm.com/email/gateway/v1/marketing" \
-H "Content-Type: application/json" \
-H "X-CM-PRODUCTTOKEN: your-product-token" \
-H "Sandbox-Mode: true" \
-d '{
  "fromAddress": "[email protected]",
  "fromName": "string",
  "replyToAddress": "[email protected]",
  "replyToName": "string",
  "toAddresses": [
    {
      "toAddress": "[email protected]",
      "toName": "string"
    }
  ],
  "ccs": [],
  "bccs": [],
  "subject": "Sandbox mode example",
  "htmlBody": "This is an example request for sandbox mode",
  "textBody": "string",
  "attachments": [],
  "customerReference": "ref-1"
}'

Response

A valid request will return a 200 OK response, indicating that your email meets all validation requirements. 

{
  "errorCode": 200,
  "details": "Sandbox mode is enabled. This message is accepted but will not be sent,",
	"messageId": "81befa16-6219-4e39-b72f-d075b6e6eeb9"
}

Note: This differs from the 202 Accepted response returned for live email requests.

If you submit a request with sandbox mode enabled, but your request body is invalid, you will receive one or more error messages with error codes.

Important Notes

  • Messages send in Sandbox Mode do not contribute to your monthly usage limit.
  • No logs are generated for requests with Sandbox Mode enabled.
  • This feature is intended for testing and validating your requests.

Integration Mode

Integration Mode let's you test the entire integration of your system with our Email Gateway. This setup provides a safe and reliable way to test your integrations and workflows without affecting real users or risking your domain reputation. By using this test domain, you can confidently fine-tune your processes while ensuring no unintended impact on your audience.

When you send an email to a recipient using the domain @sink.cm.com, our Mail Transfer Agent (MTA) will accept the message but automatically drop it. This means the email will not be delivered to any recipient's mailbox. All other processes will work the same while using Integration Mode.

❗

Please note that any messages you send to @sink.cm.com will contribute to your monthly usage limit. If you’re on a pay-as-you-go plan, these messages will be counted as billable usage.

Example Request

Here’s an example of a request in Integration Mode:

curl -X POST "https://api.cm.com/email/gateway/v1/marketing" \
-H "Content-Type: application/json" \
-H "X-CM-PRODUCTTOKEN: your-product-token" \
-H "Sandbox-Mode: true" \
-d '{
  "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"
}'

Response

In Integration Mode, the system returns the same response codes as a live integration. For example, a successful request will return a 202 OK. However, please note that while this indicates the message was sent successfully, it is not actually sent.

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

For all response codes see the response codes page.

Important Notes

When you send an email to a recipient with the domain sink.cm.com (e.g., [email protected]):

  • Our system processes the email, but ensures it is not delivered by dropping it at the Mail Transfer Agent (MTA).
  • These emails still count toward your total sent emails, as they are using the whole infrastructure.
  • In your email logs, these messages will have a status labeled as Integration, making it easy to distinguish emails sent in integration mode from regular ones.

Updated 2 days ago