Send an email

POST /emails

Send a single transactional email. The request returns immediately with a queued email ID; actual delivery happens asynchronously via the worker pool.

Body parameters

Field	Type	Required	Description
`from`	string	yes	Sender address. Must use a verified domain. Format: `"Name <email@domain>"` or `email@domain`.
`to`	string \| string[]	yes	One or more recipients (max 50).
`subject`	string	yes	Subject line (max 998 chars).
`html`	string	one of html/text	HTML body.
`text`	string	one of html/text	Plain text body.
`cc`	string \| string[]	no	Carbon-copy recipients.
`bcc`	string \| string[]	no	Blind-carbon-copy recipients.
`reply_to`	string	no	Reply-To header.
`headers`	object	no	Extra headers (`{"X-Entity-Ref-ID": "..."}`).
`attachments`	object[]	no	Array of `{filename, content (base64), content_type, content_id}`.
`tags`	object[]	no	Array of `{name, value}` for analytics filtering.
`scheduled_at`	ISO 8601	no	Delay send until this timestamp (future, up to 72h out).

Headers

Header	Description
`Idempotency-Key`	Optional. Dedupes retries within a 24h window. See Idempotency.

Example

curl -X POST https://mail.3ava.com/api/emails \
  -H "Authorization: Bearer am_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Your receipt",
    "html": "<p>Thanks for your order.</p>",
    "tags": [{"name": "category", "value": "receipt"}]
  }'

import requests

r = requests.post(
    "https://mail.3ava.com/api/emails",
    headers={"Authorization": "Bearer am_YOUR_KEY"},
    json={
        "from": "Acme <[email protected]>",
        "to": ["[email protected]"],
        "subject": "Your receipt",
        "html": "<p>Thanks for your order.</p>",
    },
)
print(r.json())

const res = await fetch("https://mail.3ava.com/api/emails", {
  method: "POST",
  headers: {
    "Authorization": "Bearer am_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "Acme <[email protected]>",
    to: ["[email protected]"],
    subject: "Your receipt",
    html: "<p>Thanks for your order.</p>",
  }),
});
console.log(await res.json());

Response

{
  "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "status": "queued",
  "created_at": "2026-04-22T22:30:00Z"
}

status progresses queued → sent → delivered (or bounced / failed / suppressed). Track it via GET /emails/:id or webhooks.

Attachments

{
  "attachments": [
    {
      "filename": "invoice.pdf",
      "content": "JVBERi0xLjQKJeLjz9MKMSAwIG9iag==",
      "content_type": "application/pdf"
    }
  ]
}

content is base64-encoded. Max total attachment size: 40MB.