Emails

API reference for sending a transactional email and reading its delivery status and events.

Using an AI agent? Just ask:“Send [email protected] a welcome email from [email protected].”Connect your agent →

Send an email#

POST/api/v1/emails

Sends one transactional email. Returns 201 with the email, or 200 when an Idempotency-Key matched an earlier request.

Body

fromstringrequired
Sender, optionally with a name: Acme <[email protected]>. Must use a verified domain.
tostringrequired
One recipient address.
subjectstring
Required unless the template has one. Liquid variables allowed.
htmlstring
The email HTML. Up to 1 MB.
textstring
Plain-text version.
templatestring
A template id or alias to use instead of html. See templates.
variablesobject
Values for Liquid variables, e.g. { "first_name": "Ada" }.
reply_tostring
Where replies go.
headersobject
Custom headers. Only X- headers are allowed.

Headers

Idempotency-Keystring
Up to 200 characters. Retries with the same key don't send twice.

Request

curl https://agent.maillayer.com/api/v1/emails \
  -H "Authorization: Bearer $MAILLAYER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: welcome-user-831" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": "[email protected]",
    "template": "welcome",
    "variables": { "first_name": "Ada" }
  }'

Response · 201

{
  "id": "6f1c0e4a-…",
  "object": "email",
  "to": "[email protected]",
  "from": "Acme <[email protected]>",
  "reply_to": null,
  "subject": "Welcome to Acme, Ada",
  "status": "queued",
  "error": null,
  "created_at": "2026-11-12T09:30:00.000Z",
  "sent_at": null,
  "delivered_at": null,
  "bounced_at": null,
  "opened_at": null,
  "clicked_at": null
}

Get an email#

GET/api/v1/emails/:id

The same fields, plus events: each delivery event with its type (such as delivered, open, click, bounce) and occurred_at.

Response · 200

{
  "id": "6f1c0e4a-…",
  "status": "delivered",
  "delivered_at": "2026-11-12T09:30:04.000Z",
  "opened_at": "2026-11-12T09:41:10.000Z",
  …,
  "events": [
    { "type": "delivered", "occurred_at": "2026-11-12T09:30:04.000Z" },
    { "type": "open", "occurred_at": "2026-11-12T09:41:10.000Z" }
  ]
}

Status values are explained in Send transactional email.