Developer docs

# Operating Sairaph Mail over REST

You can operate a Sairaph Mail mailbox through its REST API. Use it to send
email and to read inbound mail (including one-time codes) on the mailbox you
hold a key for.

## Connection

- Base URL: `https://mail.sairaph.com/api/v1`
- Auth: send `Authorization: Bearer $SAIRAPH_MAIL_KEY` on every request. The
  key is an `sm_live_...` per-mailbox key with a read or read_write role. Keep
  it secret.
- Mailbox id: your mailbox's public id looks like `mbx_...`. It goes in the
  path of every call below.

## Send an email

`POST /api/v1/mailboxes/{mailbox_id}/outbound`

- Required headers: `Authorization`, `Content-Type: application/json`, and
  `Idempotency-Key: <uuid>`. The send is rejected without the idempotency key;
  reuse the same key on a retry so a message is never sent twice.
- JSON body: `to` (array, required), `subject`, `body_text`, and optionally
  `body_html`, `cc`, `bcc`, `reply_to`. Include at least one of `body_text` or
  `body_html`.
- Returns `202` with `{ "object": "message", "id": "msg_...", "status": "queued" }`.

```bash
curl https://mail.sairaph.com/api/v1/mailboxes/$MAILBOX_ID/outbound \
  -H "Authorization: Bearer $SAIRAPH_MAIL_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["agent@acme.dev"],
    "subject": "Your verification code",
    "body_text": "Reply with APPROVE to continue."
  }'
```

## List inbound mail

`GET /api/v1/mailboxes/{mailbox_id}/messages?direction=inbound`

- Add `&live=true` to force an on-demand IMAP fetch (with a cached fallback)
  instead of serving cached envelopes. Use it when you are blocking on a code
  that may have just arrived.
- Returns a list envelope: `{ "object": "list", "data": [...], "has_more": ...,
  "next_cursor": ... }`. Each inbound row has an `object` of `cached_message`
  or `live_message` and carries a `snippet`, not the full body.
- Paginate by passing `next_cursor` back as `&cursor=...` while `has_more` is
  true.

```bash
# Read inbound from cache, or live=true for an on-demand fetch.
curl "https://mail.sairaph.com/api/v1/mailboxes/$MAILBOX_ID/messages?direction=inbound&live=true" \
  -H "Authorization: Bearer $SAIRAPH_MAIL_KEY"
```

## Read one message in full

`GET /api/v1/mailboxes/{mailbox_id}/messages/{message_id}`

- Use the `cmsg_...` id from a list row. Returns the quote-stripped `body_text`
  by default.
- Add `include=quoted` for the full thread, `include=html` for raw HTML, or
  `view=raw` for the RFC822 source. `live=true` fetches the body from source
  now.

```bash
# Read one message in full by its cmsg_… id (from a list row).
# view=full (default) returns the quote-stripped body_text; add
# include=quoted for the full thread, include=html for raw HTML.
curl "https://mail.sairaph.com/api/v1/mailboxes/$MAILBOX_ID/messages/$MESSAGE_ID?include=quoted&include=html" \
  -H "Authorization: Bearer $SAIRAPH_MAIL_KEY"
```

## Errors and limits

- Every error is a Stripe-shaped envelope: `{ "error": { "type", "code",
  "message", "param" } }`. Branch on `error.code` (stable); `message` is for
  humans.
- Common codes: `invalid_api_key` (401), `idempotency_key_required` (400),
  `message_body_required` (400), `mailbox_not_found` (404),
  `mailbox_not_active` (409), `payment_required` (402, sending is gated on
  billing; inbound reads are never gated).
- Rate limit: a `429` with a `Retry-After` header. Wait that many seconds,
  then retry.

```json
{
  "error": {
    "type": "resource_not_found",
    "code": "mailbox_not_found",
    "message": "No mailbox matches that id.",
    "param": "mailbox_id"
  }
}
```

## Where to find more

- Interactive OpenAPI reference: `https://mail.sairaph.com/docs`
- Human docs: `https://mail.sairaph.com/developers`

# Operating Sairaph Mail over MCP

Sairaph Mail runs a native Model Context Protocol server. Once it is
connected, a mailbox's actions are available to you as callable tools. Prefer
these tools for anything email-related on this mailbox.

## Connection

- Endpoint: `https://mail.sairaph.com/mcp/v1/mcp`
- Transport: streamable-HTTP.
- Auth: `Authorization: Bearer $SAIRAPH_MAIL_KEY`, the same `sm_live_...`
  per-mailbox key used for REST.
- The tools you can see are exactly the tools your key's role allows. A
  read-only key never sees mutating tools; if a tool is missing, your key
  lacks that scope.

```json
{
  "mcpServers": {
    "sairaph-mail": {
      "type": "streamable-http",
      "url": "https://mail.sairaph.com/mcp/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${SAIRAPH_MAIL_KEY}"
      }
    }
  }
}
```

## Tools

Mailbox
- `mailbox.list`, `mailbox.get` - the mailbox and its folders.
- `mailbox.overview` - triage counts (total, unread, per folder, attachments,
  last message time).
- `mailbox.set_search_indexing` - opt in or out of ranked search indexing.

Messages
- `messages.list`, `messages.get`, `messages.search` - read inbound and sent
  mail.
- `messages.send` - send a new email (needs a send-capable key).
- `messages.mark_read`, `messages.archive`, `messages.delete`, `messages.move`
  - manage one message.
- `messages.add_labels`, `messages.remove_labels` - label a message.
- `messages.batch` - apply one action to many messages at once.

Threads
- `threads.list`, `threads.get` - read conversations.
- `threads.reply` - reply in a thread (needs a send-capable key).
- `threads.mark_read`, `threads.archive`, `threads.move`, `threads.delete`,
  `threads.batch` - manage threads.

Drafts
- `drafts.create`, `drafts.get`, `drafts.list`, `drafts.update`,
  `drafts.delete`, `drafts.send`.

Folders and labels
- `folders.list`, `folders.create`, `folders.rename`, `folders.delete`.
- `labels.list`, `labels.get`, `labels.create`, `labels.update`,
  `labels.delete`.

Attachments
- `attachments.get`, `attachments.download`.

Deliverability and domains
- `bounces.list`, `suppressions.unsuppress`.
- `domains.list`, `domains.get`, `domains.dns_records`, `dns.list`.
- `events.list` - recent mailbox events.

## Notes

- Sends are idempotent server-side and gated on an active plan; inbound reads
  are never gated.
- Tool errors carry a stable `code` (for example `insufficient_scope`) you can
  branch on.

## Where to find more

- Human docs: `https://mail.sairaph.com/developers`
- Full REST and OpenAPI reference: `https://mail.sairaph.com/docs`