03 · MailMarco API

Emails

One endpoint sends everything — inline HTML, a published template, an attachment-heavy receipt, or a message scheduled for next Tuesday.

Send an email#

curl -X POST https://api.mailmarco.com/v1/emails \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "text": "Thanks for your order.",
    "tags": { "kind": "receipt" }
  }'

{
  "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "queued"
}

Request body#

Idempotency#

Pass an Idempotency-Key header to make a send safe to retry. The key is scoped to your organization and to the whole message — not to a recipient.

• First request with a given key: the message is created normally and the response has no deduped field.
• Any later request with the same key: the original message id and status come back with deduped: true. Nothing is re-sent, re-queued or re-metered.
• Two concurrent requests with the same key: exactly one wins the insert. The loser looks the winner up and returns it as deduped. No 409 is raised.
• The body is not compared. Reusing a key with different content returns the original message; it does not send the new content and does not error.

{
  "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "queued",
  "deduped": true
}

Scheduling and cancellation#

Supplying scheduledAt stores the message with status scheduled and keeps it out of the delivery queue until the scheduler promotes it. Suppression, domain and plan checks all still run at request time; the organization's paused state is re-checked again at dispatch, so a suspension between scheduling and send time still stops the message.

curl -X POST https://api.mailmarco.com/v1/emails \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Tuesday digest",
    "text": "Here is what happened.",
    "scheduledAt": "2026-08-04T07:00:00Z"
  }'

# => 202 {"id":"…","status":"scheduled"}

curl -X POST https://api.mailmarco.com/v1/emails/$MESSAGE_ID/cancel \
  -H "authorization: Bearer $MAILMARCO_API_KEY"

{
  "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "cancelled"
}

Batch send#

POST /v1/emails/batch takes 1–500 independent messages. Each one goes through the full single-send path, so templates, attachments and scheduling all work inside a batch.

curl -X POST https://api.mailmarco.com/v1/emails/batch \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "emails": [
      { "from": "[email protected]", "to": "[email protected]", "subject": "Hi A", "text": "…" },
      { "from": "[email protected]", "to": "[email protected]", "subject": "Hi B", "text": "…" }
    ]
  }'

{
  "results": [
    { "index": 0, "id": "2f9a…", "status": "queued" },
    { "index": 1, "error": "recipient suppressed: [email protected]" }
  ]
}

Results are aligned to the request order by index. A successful item carries id and status (and deduped when applicable); a failed item carries only error, a human-readable message.

Templates#

Swap subject/html/text for a template object. MailMarco renders the template's published version with your variables, HTML-escaping every interpolated value.

curl -X POST https://api.mailmarco.com/v1/emails \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "template": {
      "id": "7d3c9b21-4a5e-4f6a-8b7c-0d1e2f3a4b5c",
      "variables": { "name": "Ada", "total": "€42.00" }
    }
  }'

Rendering happens before anything is written, so an unknown or unpublished template fails fast with no partial message. You may still send subject alongside a template — it is validated but the published version's subject is what gets used.

Attachments#

Attachments are base64 in the JSON body. There is no multipart upload endpoint.

curl -X POST https://api.mailmarco.com/v1/emails \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d "{
    \"from\": \"[email protected]\",
    \"to\": \"[email protected]\",
    \"subject\": \"Your invoice\",
    \"text\": \"Invoice attached.\",
    \"attachments\": [{
      \"filename\": \"invoice.pdf\",
      \"contentType\": \"application/pdf\",
      \"content\": \"$(base64 -w0 invoice.pdf)\"
    }]
  }"

• Counts and sizes are checked before decoding. The decoded size is computed from the base64 length, so an oversized payload is a 400 without ever being buffered.
• Limits: at most 20 attachments; 10 MiB decoded per attachment; 25 MiB decoded in total.
• Every attachment is malware-scanned before the message is queued. An infected file rejects the entire send with 400 and the message is not created.
• The object key is generated server-side; your filename is kept only as metadata.

Custom headers, tags and metadata#

{
  "headers": { "X-Entity-Ref-Id": "order-2291", "List-Id": "receipts.example.com" },
  "tags": { "kind": "receipt", "tier": "pro" },
  "metadata": { "orderId": 2291, "lineItems": 3 }
}

• headers become real RFC 5322 headers on the outgoing message. Names must match ^[A-Za-z0-9-]+$; values are rejected if they contain CR or LF.
• tags are a flat string-to-string map, meant for filtering and reporting.
• metadata accepts arbitrary JSON values and is echoed back on the message; it never reaches the recipient.

Sandbox mode#

Set sandbox: true to exercise the whole request path — validation, domain checks, suppression checks, template rendering, attachment scanning, quota metering — without handing the message to the delivery queue.

{ "from": "[email protected]", "to": "[email protected]", "subject": "Smoke test", "text": "…", "sandbox": true }

A sandbox message is persisted, is visible via GET /v1/emails/:id with sandbox: true, and records two events: queued, then a simulated sent whose providerResponse is "sandbox: not delivered". Nothing is transmitted.

Retrieve a message#

{
  "id": "b1d2e3f4-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "delivered",
  "from": "[email protected]",
  "subject": "Your receipt",
  "sandbox": false,
  "createdAt": "2026-07-29T09:22:10.004Z",
  "recipients": [
    { "type": "to", "address": "[email protected]", "status": "delivered" }
  ],
  "events": [
    { "type": "queued",    "occurredAt": "2026-07-29T09:22:10.004Z", "providerResponse": null },
    { "type": "sent",      "occurredAt": "2026-07-29T09:22:11.551Z", "providerResponse": "250 OK" },
    { "type": "delivered", "occurredAt": "2026-07-29T09:22:12.907Z", "providerResponse": "250 2.0.0" }
  ]
}

Statuses

A message moves through these values:

queued · scheduled · sent · delivered · delivery_delayed
bounced · complained · opened · clicked · failed · cancelled

Listing messages is a dashboard route: GET /v1/emails?limit=&cursor=&status= takes a session token, not an API key, and returns a cursor-paginated { data, nextCursor } envelope with limit between 1 and 100 (default 25). The same is true of GET /v1/logs and GET /v1/analytics?range=30d.

Why a send gets rejected#