Skip to content
Sairaph Mail

Inbound email API

An inbound email API is an interface for receiving and reading email that arrives at an address, returning each message as structured data your code can list, page through, and act on. Two patterns exist. A webhook/parse model posts each message to your server once and stores nothing, so you must build your own storage to read it again. A stored-inbox model keeps messages in a persistent, readable mailbox you can query whenever you need them. Sairaph Mail uses the stored-inbox model: GET /api/v1/mailboxes/{id}/messages?direction=inbound returns a Stripe-style list, and live=true triggers an on-demand fetch with a cached fallback.

Get startedSee pricing

Last updated June 30, 2026

Stored inbox vs. webhook parse

The difference decides how robust your agent or automation can be. With a webhook-parse API, if your endpoint is down or you need the same message twice, the message is gone unless you stored it yourself. With a stored inbox, the message lives in the mailbox and you re-read it at will, page through history with a cursor, and poll for new mail without standing up a receiving server. For an autonomous agent - which may retry, restart, or read the same thread across steps - a stored, queryable inbox is the more reliable contract.

How Sairaph Mail exposes inbound mail

  • List inbound with GET /api/v1/mailboxes/{id}/messages?direction=inbound. The response is a Stripe-style list envelope: { object: "list", data: [...], has_more, next_cursor, url }. Paginate by passing next_cursor back as ?cursor=.
  • Read live by adding live=true - an on-demand IMAP fetch with a cached fallback if the source is briefly unreachable. Rows discriminate on object: cached_message (from the cache) vs live_message (a fresh fetch). See READ_INBOUND_CURL, READ_INBOUND_FETCH, and READ_INBOUND_PY in code-samples.ts.
  • React in real time - the mailbox tracks new inbound over IMAP IDLE, so a blocking read for a one-time code (see LIVE_OTP_CURL) returns as soon as the message lands.

Inbound message bodies are stored encrypted at rest with a per-customer key.

Related terms

  • [Two-way email API](/glossary/two-way-email-api) - pairs this inbound read side with outbound send.
  • [Programmatic mailbox](/glossary/programmatic-mailbox) - the stored inbox an inbound API reads from.
  • [Agent mailbox](/glossary/agent-mailbox) - an inbox an AI agent reads inbound mail from in real time.

Related

Give your agent a real mailbox

Two-way email over REST and a native MCP server, EU-resident by default.

Get startedSee pricing

EU data residencyPer-customer encryptionNative MCP