Read a verification code (OTP) via API

How it works in one paragraph

OTP emails are time-sensitive, so you read them with live=true - an on-demand fetch straight from the source rather than the cache. You poll the inbound list until a matching message appears, then read the code from the message (often visible in the snippet preview; pull the full body by id when you need certainty). A read-scoped key is enough - the agent never needs to send.

Before you start

• A provisioned mailbox (mbx_…) whose address you'll use as the signup/login email.
• A read-scoped sm_live_… key, set as SAIRAPH_MAIL_KEY.

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

Steps

1. Trigger the email

Have your agent (or the system under test) submit the mailbox's address to whatever sends the code - a signup form, a login 2FA step, a CI sign-in. The code is now in flight to your mailbox.

2. Poll the inbox, live

Read inbound mail with live=true so you get the freshest state rather than a cached snapshot:

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

This returns the Stripe-style list envelope. Inbound rows arrive as live_message (fresh) or cached_message, each with from_addr, subject, and a snippet preview. Loop this call on a short interval (e.g. every 2-3 seconds) with a sensible timeout (e.g. 60 seconds), filtering by the expected from_addr or subject until the code's message appears.

3. Extract the code

Most providers put the code in the subject or the first line, so the snippet preview usually contains it - match it with a regex such as \b\d{6}\b (adjust for your code length/format). When you need the complete body to be certain, fetch the message by id:

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

Use the id from the matched list row (a cmsg_… id). The default response returns the quote-stripped body_text; include=html adds the raw body_html if the code is only in an HTML part. Then run your regex over the body.

A Python sketch of the poll loop

The read call itself comes from the SSOT (READ_INBOUND_PY reads direction=inbound&live=true); wrap it in a timed loop and a regex:

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

# Pseudocode around the SSOT read above:
# 1. start = now()
# 2. while now() - start < 60s:
# 3.     messages = read inbound live  (the call above)
# 4.     for m in messages:
# 5.         if m["from_addr"] == EXPECTED_SENDER:
# 6.             match = re.search(r"\b\d{6}\b", m["subject"] + " " + m["snippet"])
# 7.             if match: return match.group(0)
# 8.     sleep(2)

Troubleshooting

• Code never arrives: confirm you submitted the mailbox's exact address; check the right from_addr; widen the timeout. Re-read with live=true (a cached read can lag).
• Code is in the body, not the snippet: fetch the message by id and add include=html if the code is HTML-only.
• Polling too aggressively: back off to 2-3 second intervals; live=true hits the source server each time.
• Multiple codes / stale code: sort by received_at and take the newest matching message so you never use an expired code.
• `429`: you're over the rate limit - honor the Retry-After header before the next poll.

Next steps

• The use-case overview: OTP & verification codes for agents.
• The general read pattern: Receive email via API.
• Full reference: the API docs.