CIA Mail API

Send mail as your domain's mailboxes, and read/answer shared mailboxes (contact@…). Keys are created by your domain administrator, each limited to scopes (send, read), mailboxes, and an hourly quota.

Base URL: https://api.cia-creative.com/v1 · machine-readable contract: openapi.json

Send

curl https://api.cia-creative.com/v1/messages \
  -H "Authorization: Bearer $CIAM_KEY" -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" -d '{
    "from": {"name": "Acme Shop", "address": "noreply@acme.com"},
    "to": ["client@example.com"],
    "subject": "Your order 1042",
    "html": "<p>Thank you!</p>"
  }'

Read and answer contact@

curl "https://api.cia-creative.com/v1/mailboxes/contact@acme.com/messages?unseen=true" -H "Authorization: Bearer $CIAM_KEY"
curl https://api.cia-creative.com/v1/mailboxes/contact@acme.com/messages/$ID/reply \
  -H "Authorization: Bearer $CIAM_KEY" -H "Content-Type: application/json" -d '{"text": "Hello, …"}'

Endpoints

POST/messagesSend a message
Queues the message and answers 202 at once; the status then goes queued → sent (or failed). Temporary SMTP failures are retried with backoff for about 5 hours. Requires the send scope; `from` must be a mailbox granted to the key.
GET/messages/{id}Status of a sent message
GET/mailboxes/{address}/foldersFolders with counts (read scope)
GET/mailboxes/{address}/messagesList messages, newest first (read scope)
GET/mailboxes/{address}/messages/{id}One message: parsed, HTML sanitised; ?format=raw for the RFC 822 source
PATCH/mailboxes/{address}/messages/{id}Mark read/flagged, or move (answers the id in the new folder)
GET/mailboxes/{address}/messages/{id}/attachments/{index}Download an attachment
POST/mailboxes/{address}/messages/{id}/replyReply (send + read scopes): threading headers set, original marked answered once sent

Errors

JSON {"error": "…"}. 401 bad key · 403 scope or mailbox not granted · 404 unknown · 413 too large · 429 quota (per key and hour) · 503 external mailbox out of reach (mailbox_disconnected: an admin must enter its new password; mail_host_unavailable: retry after Retry-After).