> ## 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`.
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`.
## 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`.
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`.
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.
description: The message payload.
metadata:
type: object
properties:
campaignType:
type: string
description: >-
Campaign type accepts only two values: "TRANSACTIONAL"
or "PROMOTIONAL".
timestamp:
type: string
custom:
type: object
properties:
inbox_tracking:
type: string
campaign_id:
type: string
description: >-
Custom key–value metadata. The 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).
description: Optional metadata recorded with the message.
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
metadata:
campaignType: transactional
timestamp: '2025-08-25T10:00:00Z'
custom:
inbox_tracking: 'true'
campaign_id: example-campaign-id
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'
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.
````