> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.mailercloud.com/llms.txt > Use this file to discover all available pages before exploring further. # 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). Need per-recipient personalization (`Hi {{first_name}}…`) in one request? Use [Send Personalized Email (mail merge)](/api-reference/email/send-personalized-email) — 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](/guides/smtp-relay) sending only; they do not affect Email API sends. ## OpenAPI ````yaml /openapi-emailapi.json post /email openapi: 3.1.0 info: title: Mailercloud Email API version: 1.0.0 description: Transactional and personalized email sending — the Mailercloud API Platform. servers: - url: https://email-api.mailercloud.com security: - apiKey: [] tags: - name: Email paths: /email: post: tags: - Email summary: Send Email description: >- 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). Need per-recipient personalization (`Hi {{first_name}}…`) in one request? Use [Send Personalized Email (mail merge)](/api-reference/email/send-personalized-email) — 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](/guides/smtp-relay) sending only; they do not affect Email API sends. operationId: send-transactional-email-api parameters: - name: Content-Type in: header required: true description: Request body type schema: type: string default: application/json requestBody: required: true content: application/json: schema: type: object required: - email - version properties: email: type: object required: - from - subject - recipients properties: from: type: string description: >- Sender email address. Must belong to a verified sender on your Mailercloud account. fromName: type: string description: >- Sender display name shown in the recipient’s inbox. Supports `{{var}}` substitution. replyTo: type: array items: type: string description: >- Address(es) replies are sent to. Must be a verified sender address; does **not** support `{{var}}` templates. subject: type: string description: Email subject line. Supports `{{var}}` substitution. text: type: string description: >- Plain-text version of the message. Supports `{{var}}` substitution. Recommended alongside `html` for deliverability. amp_html: type: string description: >- AMP for Email body. Requires `version: "2.0"`. Supports `{{var}}` substitution (not HTML-escaped). html: type: string description: >- HTML body. Supports `{{var}}` (HTML-escaped) and `{{{var}}}` (raw, unescaped — pre-trusted content only). recipients: type: object properties: to: type: array items: type: object properties: name: type: string description: Recipient display name. email: type: string description: Recipient email address. description: >- Primary recipients. Each entry may carry its own `merge_vars` object for per-recipient personalization. cc: type: array items: type: string description: >- Email addresses to receive a carbon copy, as plain strings. CC copies are rendered against the first `to` recipient’s `merge_vars`. bcc: type: array items: type: string description: >- Email addresses to receive a blind carbon copy, as plain strings. Rendered like CC against the first `to` recipient’s scope. description: Recipients of this message. attachments: type: array items: type: object properties: name: type: string description: >- File name shown to the recipient, including the extension. url: type: string description: >- Publicly accessible URL the file is fetched from at send time. description: Files to attach to the message. headers: type: object additionalProperties: type: string description: >- Custom email headers added to the message, as name–value pairs. Names are case-insensitive and must not repeat. Limits: 50 headers, 8 KB per value, 64 KB in total. Headers Mailercloud owns are rejected with `400` — see **Custom headers** above. examples: - X-Order-Reference: '10482' List-Unsubscribe: >- , List-Unsubscribe-Post: List-Unsubscribe=One-Click description: The message payload. metadata: type: object properties: campaignType: type: string description: >- Campaign type accepts only two values: "TRANSACTIONAL" or "PROMOTIONAL". timestamp: type: string messageId: type: string description: >- Your unique identifier for this message. Use a UUID, unique across your account. If omitted, the server generates one. Reusing a `messageId` within 24 hours is treated as a duplicate: the request still returns a success response (`statusCode: 1000`) but the message is not sent again, so a timed-out request can be safely retried with the same id. The value is also the basis of the message's `Message-ID` header and is shown in the Activity list, so keep it if you need to reconcile a send later. Duplicate detection applies to the Email API only — SMTP relay has none. custom: type: object properties: inbox_tracking: type: string campaign_id: type: string store_content: type: boolean default: true description: >- Set to `false` to skip storing this message's content (for example OTP or password-reset emails). Delivery and tracking are unaffected; only the message preview is unavailable in Activity. tags: type: array maxItems: 10 items: type: string maxLength: 100 description: >- Labels used to filter this message in the Activity list. Blank, duplicate and over-long tags are dropped; up to 10 tags of 100 characters each are kept. examples: - - otp - signup additionalProperties: type: string maxLength: 256 description: >- Any key other than the reserved ones is passthrough custom data. Values ≤ 256 characters; numbers and booleans are accepted and returned as strings. description: >- Custom key–value metadata. **Reserved keys** — `inbox_tracking` and `campaign_id` connect a send to inbox-placement tracking (see [List Email API Inbox-Tracking Campaigns](/api-reference/email/list-inbox-tracking-campaigns)); `store_content` and `tags` control content storage and Activity filtering. **Passthrough keys** — any other key is your own data, returned unchanged on every [transactional webhook](/guides/webhooks) event for the message inside a `custom` object, so you can match an event to your own records (order id, case id, user ref) with no lookup. Up to 10 passthrough keys; key names ≤ 50 characters using `A–Z a–z 0–9 - _`; values ≤ 256 characters, returned as strings. A key that breaks a rule is dropped and named in the webhook's `custom_dropped` array — the send always succeeds. Passthrough data is stripped before delivery and never reaches the recipient. description: >- Optional metadata recorded with the message. Always set `messageId` if you need to track delivery or reconcile webhook events. version: type: string enum: - '1.0' - '2.0' description: >- Use `1.0` when only `html` is sent. Use `2.0` when `amp_html` is included. examples: example-html-only: value: 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

Hello, this is an HTML email.

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' example-amp-html: value: email: from: from@example.com fromName: Jane Smith replyTo: - support@example.com subject: AMP Email Example text: This is the plain text version of the email. html: >-

This is the fallback HTML content.

amp_html: >-

AMP Content

Hello AMP world!

recipients: to: - name: Recipient AMP email: recipient-amp@example.com cc: - cc-amp@example.com bcc: - bcc-amp@example.com attachments: - name: manual.pdf url: https://example.com/manual.pdf metadata: campaignType: marketing timestamp: '2025-08-25T11:30:00Z' messageId: 3f9c2c6e-1b7e-4f3a-9a8d-2c1d5e7b9a10 custom: campaign_id: CAMP-123 inbox_tracking: 'true' version: '2.0' responses: '200': description: Successful Response content: application/json: schema: type: object properties: status: type: string statusCode: type: integer message: type: string examples: success: value: status: SUCCESS statusCode: 1000 message: NA '400': description: Payload Not Acceptable content: application/json: schema: type: object properties: status: type: string statusCode: type: integer message: type: string supportedVersion: type: string examples: unsupported-version: value: status: ERROR statusCode: 9022 message: Unsupported version supportedVersion: 1.0 or 2.0 servers: - url: https://email-api.mailercloud.com components: securitySchemes: apiKey: type: apiKey in: header name: Authorization description: >- Your Mailercloud API key (plain text, no Bearer prefix). Create keys in Settings → API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.