Skip to content
Sairaph Mail

Programmatic mailbox

A programmatic mailbox is a real, individually addressed email inbox that software creates, owns, and operates over an API - rather than a human clicking through a signup form. Each mailbox has its own address, stores the messages it sends and receives, and is reached with a scoped API key. It differs from a catch-all domain or an inbound route, which funnel mail for a whole domain through a single parsing pipeline without minting a distinct, persistent inbox per address. With Sairaph Mail you provision a per-address mailbox - identified by a public mbx_ id - then send and read its mail over a REST API or a native MCP server.

Get startedSee pricing

Last updated June 30, 2026

How a programmatic mailbox differs from a catch-all or route

A catch-all address or an inbound route accepts mail for an entire domain and hands it to one webhook or parser. There is no per-address inbox you can list, no stored thread history per recipient, and no isolated credential per address. A programmatic mailbox is the opposite: one minted, persistent inbox per address, each with its own stored messages, its own threading, and its own scoped key. That distinction matters when you need many independent identities - for example, a separate mailbox per agent, per customer, or per test run - instead of one shared bucket.

How it works in Sairaph Mail

You provision a mailbox on a managed domain (or your own verified domain), and the platform returns a public mbx_ id. From then on the mailbox behaves like a normal inbox that your code drives:

  • Send with POST /api/v1/mailboxes/{id}/outbound (an Idempotency-Key header is required so a retried request can never send twice). See the SEND_CURL, SEND_FETCH, and SEND_PY examples in code-samples.ts.
  • Receive and read with GET /api/v1/mailboxes/{id}/messages?direction=inbound - add live=true for an on-demand fetch with a cached fallback. See READ_INBOUND_CURL and friends in code-samples.ts.
  • Govern access with a scoped, optionally expiring key (read or read_write); message bodies and mailbox credentials are encrypted at rest with a per-customer key, and credentials are never returned by any API.

Issuance of keys is dashboard-only, not agent-callable, so a leaked key can never mint another.

Related terms

  • [Agent mailbox](/glossary/agent-mailbox) - a programmatic mailbox owned and operated by an AI agent.
  • [Inbound email API](/glossary/inbound-email-api) - the read side of a programmatic mailbox.
  • [Two-way email API](/glossary/two-way-email-api) - send, receive, and read-back as one mailbox object.
  • [Scoped API key](/glossary/scoped-api-key) - the least-privilege credential a mailbox is reached with.

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