<!-- https://docs.elchi.dev/emx-quickstart | EMX | Elchi Docs -->

# 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_`.

```bash
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

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

```json
{
  "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

```bash
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:

```bash
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:

```bash
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

```bash
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:

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

Or be told: a [webhook](/emx-webhooks) 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](/emx-errors); `message` is for a person and may change.
`requestId` is what to quote when you write to us.