Elchi Docs

↑ ↓ to move · Enter to open · Esc to close

EMX quickstart

1. A token

In the web client, Settings, Developer API: name it, pick mail:read (or mail:write to send and change things), choose when it expires. The token is shown once and starts with emx_.

export EMX_TOKEN=emx_…

A token acts as you, never with more rights than you have. It cannot open somebody else's mailbox, and it cannot make more tokens.

2. Who am I

curl -s https://mail.emxmail.app/api/me -H "Authorization: Bearer $EMX_TOKEN"

{
  "id": "…", "name": "Samuel Krauss", "role": "owner",
  "accounts": [
    {"id": "…", "kind": "user", "name": "Samuel Krauss", "address": "samuel@elchi.dev",
     "rights": {"own": true, "read": true, "write": true, "delete": true, "sendAs": true}},
    {"id": "…", "kind": "shared", "name": "Kontakt", "address": "contact@elchi.dev",
     "rights": {"read": true, "write": true, "sendAs": true}}
  ],
  "sendFrom": [{"address": "samuel@elchi.dev", "mode": "own", "primary": true},
               {"address": "contact@elchi.dev", "mode": "as"}],
  "limits": {"maxMessageBytes": 52428800, "dailyRecipients": 1000}
}

accounts is what you may open. Every mail call names one of them as {account}; me is your own.

3. The inbox

curl -s "https://mail.emxmail.app/api/accounts/me/mailboxes" -H "Authorization: Bearer $EMX_TOKEN"

Find the mailbox with "role": "inbox" and list it, newest first:

curl -s "https://mail.emxmail.app/api/accounts/me/messages?mailbox=$INBOX&limit=20" \
  -H "Authorization: Bearer $EMX_TOKEN"

Each message has id, threadId, subject, from, to, snippet, keywords ($seen, $flagged, …), hasAttachments and modseq. One message with its body:

curl -s "https://mail.emxmail.app/api/accounts/me/messages/$ID" -H "Authorization: Bearer $EMX_TOKEN"

text is the plain text, html is sanitised (no script, remote images held back in data-src), attachments carry a part path you fetch with /messages/$ID/parts/$PART.

4. Send

curl -s https://mail.emxmail.app/api/send \
  -H "Authorization: Bearer $EMX_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4711-confirmation" \
  -d '{"from": "contact@elchi.dev", "to": "Anna Beispiel <anna@beispiel-ag.ch>",
       "subject": "Bestellung 4711", "text": "Danke, wir haben alles.",
       "html": "<p>Danke, wir haben alles.</p>"}'

from must be one of your sendFrom addresses. The message is DKIM signed, filed in Sent and queued; a retry with the same Idempotency-Key within a day returns the first answer instead of sending twice.

5. Keep up

Two ways. Poll for changes with the modseq you last saw:

curl -s "https://mail.emxmail.app/api/accounts/me/changes?since=812" -H "Authorization: Bearer $EMX_TOKEN"

Or be told: a webhook on message.received calls your URL within the second, signed. For a browser or a long-running process, /api/accounts/me/events is a server-sent event stream of change events.

Errors

Every error is {"error": {"code": "…", "message": "…", "requestId": "…", "docs": "…"}} with a fitting status. code is stable and listed under Errors; message is for a person and may change. requestId is what to quote when you write to us.

3 min read