Sending email

Send with a single authenticated request to POST https://api.mail.atrix.dev/v1/emails. Authentication is an am_live_ bearer key with the email.send scope — see Authentication.

Send an email

curl -X POST https://api.mail.atrix.dev/v1/emails \
  -H "Authorization: Bearer $ATRIX_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Yourco Billing <billing@yourco.com>",
    "to": ["ava@client.io"],
    "subject": "Your March invoice",
    "html": "<p>Invoice attached. Thanks!</p>",
    "text": "Invoice attached. Thanks!",
    "reply_to": "support@yourco.com"
  }'

A successful request returns 201 Created with the message id:

{
  "id": "6f6d2b1a-3c9e-4a51-8f2b-2d7c1a0e9b44",
  "status": "queued"
}

queued means we accepted the message; delivery is asynchronous. Track it with webhooks or fetch it back with GET /v1/emails/:id (needs the emails.read scope).

Request fields

The combined recipient count across to, cc, and bcc is capped at 50 per request. Each address may be a bare addr or a Name <addr> pair.

From-address rules

The domain part of from must belong to your organization, be active (DNS verified), and have sending enabled. Otherwise the request is rejected with 403 domain_not_verified. There are no shared or sandbox sending domains — you always send from a domain you own.

Attachments

Attach files inline as base64. Each entry is { filename, content, contentType? } — the decoded total across all attachments must stay under 10 MB, with at most 20 files.

{
  "from": "billing@yourco.com",
  "to": "ava@client.io",
  "subject": "Your March invoice",
  "text": "Invoice attached.",
  "attachments": [
    {
      "filename": "invoice-1042.pdf",
      "content": "JVBERi0xLjQKJ...",     // base64
      "contentType": "application/pdf"    // optional; inferred if omitted
    }
  ]
}

Idempotency

Network timeouts happen mid-request. To retry safely, include an idempotency_key field — any unique string per logical message. If a send with that key was already accepted for your organization, the original message id is returned and no second email is sent.

curl -X POST https://api.mail.atrix.dev/v1/emails \
  -H "Authorization: Bearer $ATRIX_MAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@yourco.com",
    "to": ["ava@client.io"],
    "subject": "Your March invoice",
    "text": "Attached.",
    "idempotency_key": "invoice-1042"
  }'

Errors

Errors are JSON with a stable machine-readable code and a human message. Validation errors add a fields map keyed by the offending field:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "fields": {
      "html": "Either html or text body is required"
    }
  }
}