Inbound Email API: Receiving and Reading Email Programmatically

This pillar explains the difference between a stored two-way inbox and a webhook-only "inbound," how reading works in Sairaph Mail, and why it matters for agents.

A persistent two-way inbox vs. a webhook-only "inbound"

Most "inbound email" features fall into one of two patterns, and the difference decides what your agent can actually do:

• Webhook-parse (no stored inbox). The provider parses an incoming message and POSTs it to your server once. If you miss it, lose it, or want to re-read it later, there is nothing to list - there is no inbox, only an event that already happened.
• Domain catch-all (shared, not minted). Inbound for a whole domain lands in one place; you filter by recipient. There is no per-address mailbox object an agent owns.
• Stored, listable, per-address mailbox (Sairaph Mail). Each mailbox is a real inbox: messages are stored, threaded, listable, and individually readable over the API, for as long as the mailbox exists.

For agents, the stored inbox is the one that works, because agent tasks are reactive and often retried: you need to be able to ask "what's in this mailbox right now?" and read a specific message back.

See the glossary entries for inbound email API and two-way email API for the short definitions.

How reading inbound works in Sairaph Mail

You read a mailbox with a single endpoint:

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

It returns a Stripe-style list envelope - { object: "list", data: [ … ], has_more, next_cursor, url } - and you paginate by passing the returned next_cursor back as ?cursor=. Each inbound row carries its own object discriminator so you can tell a cached envelope from a freshly fetched one.

A read over REST:

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

The same read with a plain fetch and with Python requests is in the developer docs and the receive-email walkthrough.

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()

Cached reads vs. live=true (blocking on a code)

By default a read returns cached envelopes - fast, and fine for browsing. When an agent is blocking on something that just arrived (an OTP, a confirmation), add live=true:

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

live=true forces an on-demand IMAP fetch from the source, with a cached fallback if the source is briefly unreachable. Rows then discriminate on their object field - cached_message (from the cache) vs. live_message (a fresh fetch) - so the agent knows whether it is looking at the freshest possible state.

The classic case - reading a one-time code the instant it lands:

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

Storage, threading, and pagination

• Stored: inbound messages persist in the mailbox; they are not consumed by a single read.
• Threaded: the mailbox is a real conversation store, so replies belong to a thread rather than arriving as orphan events.
• Paginated: the list envelope returns has_more and next_cursor; pass the cursor back as ?cursor= to page through. This is the same cursor model the rest of the API uses.

Full request/response shapes are in the API reference.

The EU-residency wedge

Inbound mail is the most sensitive surface - it is where verification codes, replies, and personal content land. Sairaph Mail stores inbound in EU-resident mailboxes (OVHcloud) with each customer's message bodies encrypted at rest under a dedicated per-customer key, and the company is EU-incorporated. That combination - a real, readable inbox *and* EU residency by default on every plan - is the lane we occupy. (See the email-for-AI-agents pillar for how this sits in the broader product.)

Next step: follow the Quickstart to provision a mailbox and read your first inbound message, or read the docs at https://mail.sairaph.com/docs.