https://email-api.mailercloud.com — separate from the campaign API.
Set version to "1.0" when sending html only, or "2.0" when including amp_html.
Per-recipient personalization (mail merge)
To personalize each recipient’s email in a single request —Hi {{first_name}}, your order {{order.id}} shipped — use the mail merge endpoint: same request structure at POST /email-api, plus a merge_vars object on each recipients.to[] entry.
Attachments
Pass anattachments array with a name and a publicly fetchable url per file — see the full reference.
Custom headers
Add your own headers withemail.headers — for example a correlation id, or a one-click
unsubscribe link of your own:
List-Unsubscribe values must be angle-bracketed https:// or mailto: URIs, and
List-Unsubscribe-Post must be exactly List-Unsubscribe=One-Click. Headers Mailercloud sets
itself — From, Message-ID, DKIM-Signature and similar — are rejected with 400; use
from, metadata.messageId and the other request fields instead. Limits are 50 headers, 8 KB
per value and 64 KB in total. The full reference lists every
reserved header.
Custom data on webhooks
Add your own keys tometadata.custom and Mailercloud returns them on every
transactional webhook event for that message — Sent, Delivery, Open, Bounce,
Spam, Reject — so you can tie an event back to your own order, case, or user record with no lookup.
custom object, as strings:
- Up to 10 custom keys per message. Key names are ≤ 50 characters using
A–Z a–z 0–9 - _; values are ≤ 256 characters and come back as strings (numbers and booleans are coerced). - A key that breaks a rule is dropped and named in the event’s
custom_droppedarray — the email is always sent, never blocked by custom data. - The reserved keys
inbox_tracking,campaign_id,store_contentandtagskeep their special meaning and are never echoed back. - Custom data is stripped before delivery and never reaches the recipient.
X-MC-Custom-* headers — see SMTP relay.
Tracking and duplicates
- Opens are tracked automatically when your sending domain has a tracking domain configured. There is no per-message parameter on the API; the domain-level Open Tracking switch and the
mld-track-opensheader apply to SMTP relay only. - Clicks are not tracked.
- Inbox placement uses
metadata.custom.inbox_trackingandmetadata.custom.campaign_id. - Duplicates: reusing a
metadata.messageIdwithin 24 hours returns success without sending again, so a timed-out request is safe to retry with the same id. SMTP relay has no equivalent. - Sensitive content: set
metadata.custom.store_contenttofalseon OTP or password-reset emails to skip storing the message body. Delivery and tracking are unaffected.