Give your AI agent an email address

Why not just use a Gmail account?

The clean path through Gmail and other mainstream providers is closed to software. Mainstream providers have retired password-based access and require OAuth; to let an app read or receive mail unattended you face app verification plus third-party security audits re-passed every year (Google's CASA), or an admin-controlled paid workspace. Consumer signups are gated by CAPTCHA and phone checks under Terms that forbid automated account creation. Rolling your own means a registrar, DNS, DKIM/SPF/DMARC, an SMTP relay, an IMAP loop, and a secrets store.

Sairaph Mail gives the agent its own real mailbox with a scoped key - none of that. The mailbox is EU-hosted (OVHcloud storage plus an Amazon SES relay in eu-west-1), and each customer's message bodies and mailbox credentials are encrypted at rest with a per-customer key.

Before you start

• A Sairaph Mail account (every plan includes an instant mailbox on a Sairaph domain, for example you@sairaph.email).
• 5-10 minutes. No code is strictly required for steps 1-2 (they're dashboard clicks); steps 4-5 show the API your agent calls.

Steps

1. Create an account and provision a mailbox

Sign up, then go to Dashboard → Mailboxes → New mailbox. Pick a mailbox on a Sairaph domain (instant, no DNS), or bring your own domain and verify it with the DNS records the dashboard shows you if you want a custom address. When the mailbox is ready it has a public id of the form mbx_… - you'll pass this id on every API call.

2. Issue a scoped API key

Keys are issued from the dashboard, never over the API - the issuance surface is deliberately not agent-callable, so a leaked key can't mint or revoke another. Go to Dashboard → API keys, pick the mailbox, choose a role (read, read_write, or management) and an optional expiry, and copy the sm_live_… secret. It is shown once.

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

Give your agent a read_write key if it needs to send and receive; read is enough for an agent that only reads codes or replies.

3. Give the key to your agent

Set the key as an environment variable wherever your agent runs, and pass it as a Bearer token on every REST and MCP call. (The export line above does this.) Never hardcode it in source or commit it.

4. Send the first email

Have the agent send a message from its mailbox. The Idempotency-Key header is required on send, so a retried request can never send the same email twice.

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."
  }'

Expected response (202 Accepted):

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

5. Read the inbox

Have the agent read what's arrived. direction=inbound reads cached envelopes; add live=true to force an on-demand IMAP fetch with a cached fallback.

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

You get a Stripe-style list envelope: { "object": "list", "data": [ … ], "has_more": …, "next_cursor": … }. Each inbound row is a cached_message (from the cache) or a live_message (a fresh fetch).

6. (Optional) Connect over MCP instead of REST

If your agent runtime speaks the Model Context Protocol, point it at the MCP server and the mailbox's actions show up as tools - no REST wiring needed. The endpoint uses the same sm_live_… mailbox key as a Bearer token.

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

Troubleshooting

• `401`/`403` on a call: the key is missing, wrong, expired, or scoped too low (e.g. a read key trying to send). Re-issue with the right role in the dashboard.
• Send rejected without an `Idempotency-Key`: the header is required on send. Generate a fresh UUID per logical send (uuidgen / crypto.randomUUID() / uuid.uuid4()).
• `404` "mailbox not found": you passed an email address instead of the mbx_… public id, or the key belongs to a different mailbox.
• Inbound looks empty: newly provisioned mailboxes have nothing yet - send the mailbox a test email first, then re-read with live=true.

Next steps

• Read a verification code (OTP) via the API
• Receive email via API: a working walkthrough
• Quickstart: zero to send + receive in 10 minutes
• For a no-code wiring, see the no-code operators page.