Quickstart: from zero to send + receive in 10 minutes

What you'll have at the end

• A provisioned mailbox with a mbx_… public id.
• A scoped sm_live_… key your agent uses on every call.
• A sent email and a read inbox - over REST.
• The same mailbox wired into an MCP-capable agent runtime.

Before you start

• A Sairaph Mail account (every plan includes a mailbox to follow this).
• A terminal with curl (the snippets also come in fetch and Python on the API docs).

Steps

1. Provision a mailbox (≈2 min)

In Dashboard → Mailboxes → New mailbox, pick a mailbox on a Sairaph domain (instant, e.g. you@sairaph.email) or bring your own domain and add the DNS records shown if you want a custom address. When it's ready, copy its public id - mbx_…. You'll substitute this for $MAILBOX_ID below.

2. Issue and export a key (≈2 min)

Keys are dashboard-issued only (the issuance surface is not agent-callable by design). In Dashboard → API keys, pick the mailbox, choose read_write (so you can both send and read) and an optional expiry, and copy the sm_live_… secret - it's shown once. Then export it:

# Keys are issued from the dashboard, not over REST - the issuance surface is
# deliberately not agent-callable, so a leaked key can never mint or revoke
# another. To get one: Dashboard → API keys → pick the mailbox + a role
# (read / read_write / management) + an optional expiry → copy the sm_live_…
# secret (it is shown ONCE). Then set it for your agent and pass it as the
# Bearer token on every REST + MCP call:
export SAIRAPH_MAIL_KEY="sm_live_…"

3. Send your first email (≈2 min)

The Idempotency-Key header is required on send, so a retried request can never double-send.

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."
  }'

Expected response (202 Accepted):

{ "object": "message", "id": "msg_…", "status": "queued" }

4. Read the inbox (≈2 min)

Send the mailbox a test email from any account, then read inbound. direction=inbound reads the cache; live=true forces an on-demand fetch.

# 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"

You'll get a Stripe-style list envelope; each inbound row is a cached_message or live_message with from_addr, subject, and a snippet. (Full read + pagination details: Receive email via API.)

5. Connect over MCP (≈2 min, optional)

If your agent runtime speaks MCP, register the server and the mailbox's actions appear as tools - same sm_live_… key as a Bearer token, streamable-HTTP transport. The bare endpoint:

https://mail.sairaph.com/mcp/v1/mcp
Authorization: Bearer $SAIRAPH_MAIL_KEY

For a Claude Desktop-style client config:

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

More client configs (remote runtimes, generic clients) are on the MCP page.

When something goes wrong

Errors use a Stripe-shaped envelope, so you can branch on error.type / error.code:

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

• Send rejected: add the required Idempotency-Key header (a fresh UUID per send).
• `401`/`403`: key missing/expired, or scoped too low for the action (read can't send).
• `404` mailbox not found: you passed an email address instead of the mbx_… id, or the key is bound to a different mailbox.
• `429`: over the rate limit - wait for the Retry-After interval and retry.

Next steps

• Wire it into a framework or runtime: the developer quickstart and MCP guide.
• Real-time reads in depth: Receive email via API.
• The classic agent task: Read a verification code (OTP).