Receive email via API: a working walkthrough

The one endpoint you need

Inbound mail is read with a single call:

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

direction=inbound selects received mail (the default in a mailbox context). Add live=true to force an on-demand IMAP fetch with a cached fallback if the source is briefly unreachable. The response is a Stripe-style list envelope, and each inbound row carries an object discriminator: cached_message (served from our cache) or live_message (a fresh fetch).

Before you start

• A provisioned mailbox (mbx_… public id) - see Give your agent an email.
• A read or read_write API key (sm_live_…), set as SAIRAPH_MAIL_KEY.

Steps

1. Read inbound mail from the cache (with cURL)

Start with the simplest read. Without live=true you read cached envelopes - fast, and enough for most polling.

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

Expected response shape:

{
  "object": "list",
  "data": [
    {
      "object": "cached_message",
      "id": "cmsg_…",
      "from_addr": "sender@example.com",
      "to_addrs": ["agent@acme.dev"],
      "subject": "Re: your request",
      "snippet": "Sounds good - approved.",
      "received_at": "2026-06-30T10:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The list rows are envelopes with a snippet (a short preview), not the full body. To pull a whole message body, fetch it by id (step 5).

2. Read inbound mail from your code

The same call from a plain fetch (no SDK):

const API_ORIGIN = "https://mail.sairaph.com"
const MAILBOX_ID = "mbx_…" // your mailbox's public id

// direction=inbound reads cached envelopes; live=true forces an on-demand
// IMAP fetch with a cached fallback if the source is briefly unreachable.
const res = await fetch(
  `${API_ORIGIN}/api/v1/mailboxes/${MAILBOX_ID}/messages?direction=inbound&live=true`,
  { headers: { Authorization: `Bearer ${process.env.SAIRAPH_MAIL_KEY}` } },
)

// { object: "list", data: [ … ], has_more, next_cursor, url }
const { data: messages } = await res.json()

…or from Python with requests:

import os

import requests

API_ORIGIN = "https://mail.sairaph.com"
MAILBOX_ID = "mbx_…"  # your mailbox's public id

# direction=inbound reads cached envelopes; live=true forces an on-demand
# IMAP fetch with a cached fallback if the source is briefly unreachable.
resp = requests.get(
    f"{API_ORIGIN}/api/v1/mailboxes/{MAILBOX_ID}/messages",
    params={"direction": "inbound", "live": "true"},
    headers={"Authorization": f"Bearer {os.environ['SAIRAPH_MAIL_KEY']}"},
    timeout=30,
)

# { "object": "list", "data": [ … ], "has_more": …, "next_cursor": …, "url": … }
# Rows discriminate on "object": "cached_message" vs "live_message".
# Paginate by passing the returned next_cursor back as ?cursor=.
messages = resp.json()["data"]

3. Force a live fetch for real-time reads

When you need the very latest - for example an agent waiting on a reply - pass live=true. This does an on-demand IMAP fetch and falls back to the cache if the source is momentarily unreachable (the envelope carries a live_fallback flag when that happens). Live rows arrive with "object": "live_message".

> Tip: poll the cached read on a loop and only escalate to live=true when you actually need the freshest state - it's the cheaper path.

4. Page through results

The list envelope is cursor-paginated. When has_more is true, pass the returned next_cursor back as ?cursor= to get the next page:

GET /api/v1/mailboxes/{mailbox_id}/messages?direction=inbound&cursor={next_cursor}

Keep following next_cursor until has_more is false.

5. Read one message in full

The list returns previews. To get a full message body, fetch it by its id:

GET /api/v1/mailboxes/{mailbox_id}/messages/{msg_id}

Use the id from a list row (a cmsg_… cached-inbound id). By default this returns the quote-stripped body_text plus a quote_stripped honesty flag; add include=quoted for the unstripped body_text_full, include=html for the raw body_html, or view=raw for the full RFC822 source.

Errors

Errors use a Stripe-shaped envelope. A bad mailbox id, for instance:

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

Over-limit responses on the agent API are 429 with a Retry-After header - honor it and retry after the stated delay.

Troubleshooting

• Empty `data` array: nothing has arrived yet, or you're reading the cache before the first sync - send the mailbox a test email and re-read with live=true.
• `live=true` is slow: that's expected; it hits the source IMAP server. Prefer cached reads for routine polling.
• `401`/`403`: key missing, expired, or scoped below read. Re-issue in the dashboard.
• Missing body: list rows only carry snippet. Fetch the message by id (step 5) for the full body.

Next steps

• Read a verification code (OTP) via the API - the real-time read pattern in practice.
• Quickstart: zero to send + receive.
• Full reference: the API docs.