Skip to content
Sairaph Mail

Two-way email API

A two-way email API lets software both send and receive mail through one persistent mailbox, then read the replies back as structured data - send, receive, and read-back against a single inbox object. It contrasts with a send-only transactional API, which is built to fire messages out and gives no stored inbox to read from. Most email APIs are built to send; a two-way API treats the mailbox as something your code owns and operates in both directions. Sairaph Mail exposes a two-way mailbox over a REST API and a native MCP server: outbound on POST /api/v1/mailboxes/{id}/outbound, inbound on GET /api/v1/mailboxes/{id}/messages.

Get startedSee pricing

Last updated June 30, 2026

Why "two-way" is the load-bearing distinction

Many tasks only work if the same identity can send *and* read. Confirming a signup, catching a one-time code, handling a reply, or running a back-and-forth conversation all require reading the response to something you sent - and reading it against the address that sent it. A send-only API can deliver the first message but leaves you to assemble receiving, storage, and threading from other tools. A two-way API closes that loop: one mailbox, one credential, one consistent shape for both directions.

How Sairaph Mail implements two-way

  • Send - POST /api/v1/mailboxes/{id}/outbound with a required Idempotency-Key header. Returns 202 with { object: "message", id: "msg_…", status: "queued" }. See SEND_CURL, SEND_FETCH, SEND_PY in code-samples.ts.
  • Receive and read - GET /api/v1/mailboxes/{id}/messages?direction=inbound returns a Stripe-style list; live=true adds an on-demand fetch with a cached fallback. See READ_INBOUND_CURL and friends.
  • Over MCP too - the same mailbox is reachable from an MCP-capable agent at /mcp/v1/mcp (streamable-HTTP), authenticated with the same scoped mailbox key. See MCP_CLAUDE_DESKTOP and MCP_GENERIC_CLIENT.

Both directions run against one mailbox object, with messages stored encrypted at rest under a per-customer key.

Related terms

  • [Inbound email API](/glossary/inbound-email-api) - the receive/read half of a two-way API.
  • [Programmatic mailbox](/glossary/programmatic-mailbox) - the persistent inbox a two-way API acts on.
  • [Agent mailbox](/glossary/agent-mailbox) - a two-way mailbox owned and operated by an AI agent.

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