Email built for the agent, not the human

How it works

1. 01Issue a scoped, expiring key

   Per-inbox keys carry one role - read, read-write, or management - with an optional expiry, so an agent gets least privilege.

   Shell

   Show example

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

2. 02Send idempotently

   An Idempotency-Key header makes retries safe.

   cURL

   Show example

   # Pass a unique Idempotency-Key on every mutating call so a retried request
   # can never send the same email twice. On send the header is REQUIRED - the
   # request is rejected without it.
   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."
     }'

3. 03Read errors you can branch on

   A Stripe-shaped envelope: type, code, message, param.

   JSON

   Show example

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

4. 04Back off on 429

   Hit the per-key limit and you get a 429 with Retry-After.

5. 05Get inbound in real time

   IMAP IDLE plus a poll fallback, and ?live=true for an on-demand fetch.

   cURL

   Show example

   # Blocking on a one-time code? Fetch inbound straight from the source.
   curl "https://mail.sairaph.com/api/v1/mailboxes/$MAILBOX_ID/messages?direction=inbound&live=true" \
     -H "Authorization: Bearer $SAIRAPH_MAIL_KEY"

6. 06Or skip REST entirely with MCP

   Point your MCP client at the endpoint and the mailbox's actions become tools.

   claude_desktop_config.json

   Show example

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