curl --request POST \
  --url https://email-api.mailercloud.com/email \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "email": {
    "from": "from@example.com",
    "fromName": "John Doe",
    "replyTo": [
      "replyto@example.com"
    ],
    "subject": "HTML Email Example",
    "text": "This is the plain text version of the email.",
    "html": "<html><body><h1>HTML Body</h1><p>Hello, this is an HTML email.</p></body></html>",
    "recipients": {
      "to": [
        {
          "name": "Recipient One",
          "email": "recipient1@example.com"
        },
        {
          "name": "Recipient Two",
          "email": "recipient2@example.com"
        }
      ],
      "cc": [
        "cc1@example.com",
        "cc2@example.com"
      ],
      "bcc": [
        "bcc1@example.com"
      ]
    },
    "attachments": [
      {
        "name": "file1.pdf",
        "url": "https://example.com/file1.pdf"
      },
      {
        "name": "image.png",
        "url": "https://example.com/image.png"
      }
    ],
    "headers": {
      "X-Order-Reference": "10482"
    }
  },
  "metadata": {
    "campaignType": "transactional",
    "timestamp": "2025-08-25T10:00:00Z",
    "messageId": "order-10482-confirmation",
    "custom": {
      "inbox_tracking": "true",
      "campaign_id": "example-campaign-id",
      "store_content": false,
      "tags": [
        "order-confirmation"
      ],
      "order_ref": "10482"
    }
  },
  "version": "1.0"
}
'

{
  "status": "SUCCESS",
  "statusCode": 1000,
  "message": "NA"
}

{
  "status": "ERROR",
  "statusCode": 9022,
  "message": "Unsupported version",
  "supportedVersion": "1.0 or 2.0"
}

Send Email

Send a single email — transactional (order confirmations, OTPs, notifications) or promotional — through the Mailercloud Email API. Supports plain text, HTML, AMP content, attachments, and multiple recipients (To, CC, BCC).

Key points:

from (and replyTo) must belong to a verified sender on your account.
Set version to "1.0" for HTML-only sends, or "2.0" when including amp_html.
Provide both html and text for the best deliverability.
Attachments are fetched at send time from a publicly accessible url.
Set metadata.messageId to your own unique id (a UUID).
At most 1,000 recipients per request, counting to, cc and bcc together; at least one to recipient is required. Exceeding the limit returns HTTP 400 with statusCode: 9999 and the message Total recipients should not exceed 1000.

Need per-recipient personalization (Hi {{first_name}}…) in one request? Use Send Personalized Email (mail merge) — same request structure plus merge_vars.

Custom headers

Pass additional headers in email.headers as name–value pairs, for example X-Order-Reference for your own correlation id.

List-Unsubscribe must be one or more comma-separated values in angle brackets, each starting with https:// or mailto: (plain http:// is rejected). A value you supply replaces the one Mailercloud adds by default.
List-Unsubscribe-Post must be exactly List-Unsubscribe=One-Click and requires List-Unsubscribe in the same request.
Headers Mailercloud sets itself cannot be overridden and return 400: From, Sender, Reply-To, Return-Path, To, Cc, Bcc, Subject, Message-ID, Date, In-Reply-To, References, MIME-Version, any Content-*, DKIM-Signature, ARC-*, Authentication-Results, Received, List-Id, List-Help, List-Subscribe, List-Archive, List-Owner, List-Post, Feedback-ID, CFBL-Address, CFBL-Feedback-ID, Errors-To, Precedence, Auto-Submitted, X-Mailer, X-Tracking-Id, and any mld-track-* header. Use from / fromName, replyTo, subject and metadata.messageId instead.
Limits: 50 headers, 8 KB per value, 64 KB in total.

Tracking

Opens are tracked automatically whenever your sending domain has a tracking domain configured. The Email API has no per-message open-tracking parameter.
Clicks are not tracked.
Inbox placement is enabled with metadata.custom.inbox_tracking and metadata.custom.campaign_id.

The domain-level Open Tracking switch and the mld-track-opens header apply to SMTP relay sending only; they do not affect Email API sends.

POST

curl --request POST \
  --url https://email-api.mailercloud.com/email \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "email": {
    "from": "from@example.com",
    "fromName": "John Doe",
    "replyTo": [
      "replyto@example.com"
    ],
    "subject": "HTML Email Example",
    "text": "This is the plain text version of the email.",
    "html": "<html><body><h1>HTML Body</h1><p>Hello, this is an HTML email.</p></body></html>",
    "recipients": {
      "to": [
        {
          "name": "Recipient One",
          "email": "recipient1@example.com"
        },
        {
          "name": "Recipient Two",
          "email": "recipient2@example.com"
        }
      ],
      "cc": [
        "cc1@example.com",
        "cc2@example.com"
      ],
      "bcc": [
        "bcc1@example.com"
      ]
    },
    "attachments": [
      {
        "name": "file1.pdf",
        "url": "https://example.com/file1.pdf"
      },
      {
        "name": "image.png",
        "url": "https://example.com/image.png"
      }
    ],
    "headers": {
      "X-Order-Reference": "10482"
    }
  },
  "metadata": {
    "campaignType": "transactional",
    "timestamp": "2025-08-25T10:00:00Z",
    "messageId": "order-10482-confirmation",
    "custom": {
      "inbox_tracking": "true",
      "campaign_id": "example-campaign-id",
      "store_content": false,
      "tags": [
        "order-confirmation"
      ],
      "order_ref": "10482"
    }
  },
  "version": "1.0"
}
'

{
  "status": "SUCCESS",
  "statusCode": 1000,
  "message": "NA"
}

{
  "status": "ERROR",
  "statusCode": 9022,
  "message": "Unsupported version",
  "supportedVersion": "1.0 or 2.0"
}

Authorizations

Authorization

string

header

required

Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API.

Headers

Content-Type

string

default:application/json

required

Request body type

Body

application/json

object

required

The message payload.

Show child attributes

version

enum<string>

required

Use 1.0 when only html is sent. Use 2.0 when amp_html is included.

Available options:

1.0,

2.0

metadata

object

Optional metadata recorded with the message. Always set messageId if you need to track delivery or reconcile webhook events.

Show child attributes

Response

Successful Response

status

string

statusCode

integer

message

string