Send Email

SendEmail sends a single transactional email POST /api/v1/emails Requires a verified owned sender and stable Idempotency-Key. Base64 attachments preserve name, type (MIME), disposition and cid. Same key+content retries return the original result; changed payload is 409. A batch holds one content-bound key for the whole ordered request plus per-item keys. Inspect each item's success/error; retry the identical batch for incomplete items. queued/pending is not provider acceptance. sent is SES acceptance; delivered is destination-server acceptance. unknown needs investigation and must not be blindly retried with a new key.

Authentication & compatibility

Use a scoped bearer API key with email:send. The key is bound to its user and organization.

SES email workflow and its stored mailbox/configuration data. Provider actions require configured AWS permissions and verified owned domains; receiving is opt-in.

Contract 2026-10-04. Your running instance's /api/v1/openapi.json is authoritative for its deployed release.

Request

Set MAILAT_BASE_URL to your instance origin (without /api/v1) and MAILAT_TOKEN to an appropriate credential. Replace path placeholders and example data before running. These examples do not execute in this page.

curl --request POST "$MAILAT_BASE_URL/api/v1/emails" \
  --header "Authorization: Bearer $MAILAT_TOKEN" \
  --header "Idempotency-Key: replace-with-a-stable-job-key" \
  --header 'Content-Type: application/json' \
  --data '{
  "attachments": [
    {
      "content": "SGVsbG8=",
      "name": "hello.txt",
      "type": "text/plain"
    }
  ],
  "from": "[email protected]",
  "subject": "Welcome",
  "text": "Hello from Mailat",
  "to": [
    "[email protected]"
  ]
}'

Responses

HTTP statuses and body shapes below come from the pinned contract. Not every shared error applies to every request. Retain the original idempotency key when retrying a send.