Skip to main content
Transactional emails (order confirmations, password resets, OTPs) use the dedicated Email API at 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 an attachments array with a name and a publicly fetchable url per file — see the full reference.

Custom headers

Add your own headers with email.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 to metadata.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.
Each event then carries your keys back, inside a 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_dropped array — the email is always sent, never blocked by custom data.
  • The reserved keys inbox_tracking, campaign_id, store_content and tags keep their special meaning and are never echoed back.
  • Custom data is stripped before delivery and never reaches the recipient.
Sending over SMTP instead? Use the 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-opens header apply to SMTP relay only.
  • Clicks are not tracked.
  • Inbox placement uses metadata.custom.inbox_tracking and metadata.custom.campaign_id.
  • Duplicates: reusing a metadata.messageId within 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_content to false on OTP or password-reset emails to skip storing the message body. Delivery and tracking are unaffected.