Switching to Sairaph Mail

Before you start

• A Sairaph Mail account. Every plan includes an instant mailbox on a Sairaph brand domain, so you can send and receive before any DNS is touched.
• Access to your domain's DNS host, only if you are bringing a custom domain.
• Your agent's current sending code, so you can repoint it.

1. Point a domain at Sairaph, or start on a brand domain

You have three options, and only one of them involves DNS.

• Use a Sairaph brand domain (no DNS). Hosted mailboxes default to sairaph.email, sai.email, or sent.ac. They are ready the moment you create them, with DKIM, suppression, and the relay handled for you. If a branded-but-not-your-own address is fine, skip straight to step 2.
• Buy a custom domain through Sairaph. On a plan that includes a domain credit (Agent and up), you can register a domain at checkout. Sairaph places the order through its registrar, attaches its nameservers, and configures it to host email. Provisioning is asynchronous and the dashboard shows live status. There is no DNS for you to edit in this path.
• Bring a custom domain you already own. Add the DNS records the dashboard shows you at your current registrar or DNS host - an MX record plus a DKIM key - publish them, and Sairaph verifies the domain before it can host mailboxes. Once verified it behaves like a managed domain, with DKIM signing, suppression, and the SES relay handled for you.

Two honest limits to plan around: the first-domain credit covers first-year *registration* on a domain you buy through Sairaph, so a domain you bring has nothing to register and the credit does not apply to it; and *transfer-in* (moving a domain's registration over to Sairaph) is planned for a later release, not available today. See the domains FAQ for the details per plan.

2. Provision your hosted mailboxes

In Dashboard → Mailboxes → New mailbox, create each mailbox your agents need on a brand domain or your verified custom domain. Each mailbox has a public id of the form mbx_… - the id you pass on every API call, in place of an email address.

Then issue a scoped API key per the access each agent needs. Keys are dashboard-issued only; the issuance surface is deliberately not agent-callable, so a leaked key cannot mint or revoke another. Pick read_write for an agent that sends and reads (it also carries the suppression scopes you need in step 4), or read for one that only reads codes or replies.

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

For the full walkthrough of provisioning and keys, see give your AI agent an email address.

3. Repoint your agent's send and receive calls

Sairaph Mail's agent-facing surface is a REST API and a first-party MCP server, not an SMTP host. Migrating your send path means swapping your old provider's API call for Sairaph's endpoint and auth, not reconfiguring an SMTP relay in your agent.

To send, call the outbound endpoint with your sm_live_… key as a Bearer token. The Idempotency-Key header is required on send, so a retried request can never double-send.

curl https://mail.sairaph.com/api/v1/mailboxes/$MAILBOX_ID/outbound \
  -H "Authorization: Bearer $SAIRAPH_MAIL_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["agent@acme.dev"],
    "subject": "Your verification code",
    "body_text": "Reply with APPROVE to continue."
  }'

The call returns immediately with a server-generated id while a background worker delivers via the relay with retries:

{ "object": "message", "id": "msg_…", "status": "queued" }

To receive - the half a transactional send-API usually cannot give you - read inbound over the same REST surface. direction=inbound reads the cache; add live=true to force an on-demand fetch with a cached fallback, which is the pattern you want when an agent is blocking on a one-time code or a reply.

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

If your agent runtime speaks MCP, point it at the server instead and the mailbox's actions appear as tools, authed with the same key.

https://mail.sairaph.com/mcp/v1/mcp
Authorization: Bearer $SAIRAPH_MAIL_KEY

4. Reconcile your suppression list

Be precise about what "porting a suppression list" means here, because Sairaph's suppression model is not an upload target.

Sairaph maintains a suppression list per mailbox, automatically: hard bounces and complaints are suppressed for you as they happen, so you do not resend to an address that already bounced or complained. The API lets you read and lift those entries, but there is no bulk-import endpoint to preload your previous provider's list. Concretely, with a read_write (or management) key you can:

# List active suppressions, optionally filtered by mailbox and recipient
curl "$SAIRAPH_API/api/v1/suppressions?mailbox_id=$MAILBOX_ID" \
  -H "Authorization: Bearer $SAIRAPH_KEY"

# Lift one suppression by mailbox + recipient (an MCP-friendly alias)
curl -X DELETE \
  "$SAIRAPH_API/api/v1/mailboxes/$MAILBOX_ID/suppressions/blocked@example.com" \
  -H "Authorization: Bearer $SAIRAPH_KEY"

Lifting is deliberate and safe: Sairaph clears the entry at the upstream mail provider first and only then marks it lifted, so a success response always means the recipient is genuinely unsuppressed. The row is kept for audit history rather than hard-deleted.

So the practical migration play is:

1. Export your old provider's suppression list and keep it as your own known-bad set. Since there is no import, the cleanest protection is to have your agent skip sends to those addresses until Sairaph's own list rebuilds naturally from live bounces and complaints.
2. Do not re-send to a previously bouncing address just because Sairaph starts clean. A fresh list does not make a dead mailbox deliverable; it just means Sairaph has not learned it yet.
3. Lift a false positive with the calls above if a real recipient was suppressed by mistake.

For how the guard rails behave (bounce-and-complaint thresholds, throttling, and per-mailbox reputation), see the deliverability FAQ.

When something goes wrong

• `404` "mailbox not found": you passed an email address instead of the mbx_… public id, or the key is bound to a different mailbox.
• `401`/`403`: the key is missing, expired, or scoped too low - a read key cannot send, and it cannot lift a suppression (that needs the suppression scopes on a read_write or management key).
• Custom domain will not verify: confirm the MX and DKIM records were published exactly as the dashboard shows, and that they have propagated at your DNS host before retrying verification.
• Send rejected: add the required Idempotency-Key header (a fresh UUID per logical send).

Next steps

• Quickstart: zero to send + receive in 10 minutes
• Give your AI agent an email address
• Email for AI agents · Security