From zero to your first email

The fastest path from signup to sending and receiving. You'll need an account to issue keys — start there.

Step by step

1. 01Verify your email

   You can browse the dashboard right after signup, but you can't order a domain, create a mailbox, or send until you verify.

2. 02Order a domain

   Your first-year registration is covered by your plan's domain credit.

3. 03Create a mailbox

   Provisioned on OVH against your verified domain.

4. 04Issue a scoped API key

   In the dashboard: API keys → pick the mailbox + a role (read, read_write, or management) + an optional expiry, then copy the sm_live_… secret — it's shown once. Set it as SAIRAPH_MAIL_KEY for your agent.

5. 05Send your first email over REST

   One idempotent POST sends from your managed mailbox — over the root origin /api/v1, in cURL or Python.

   cURL

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

   Python

   import os
   import uuid
   
   import requests
   
   API_ORIGIN = "https://mail.sairaph.com"
   MAILBOX_ID = "mbx_…"  # your mailbox's public id (Dashboard → Mailboxes)
   
   resp = requests.post(
       f"{API_ORIGIN}/api/v1/mailboxes/{MAILBOX_ID}/outbound",
       headers={
           "Authorization": f"Bearer {os.environ['SAIRAPH_MAIL_KEY']}",
           # REQUIRED on send — a retried request can never send the mail twice.
           "Idempotency-Key": str(uuid.uuid4()),
       },
       json={
           "to": ["agent@acme.dev"],
           "subject": "Your verification code",
           "body_text": "Reply with APPROVE to continue.",
       },
       timeout=30,
   )
   
   # 202 Accepted → { "object": "message", "id": "msg_…", "status": "queued" }
   message = resp.json()

6. 06Read inbound

   From cache, or ?live=true for an on-demand fetch.

   cURL

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

   Python

   import os
   
   import requests
   
   API_ORIGIN = "https://mail.sairaph.com"
   MAILBOX_ID = "mbx_…"  # your mailbox's public id
   
   # direction=inbound reads cached envelopes; live=true forces an on-demand
   # IMAP fetch with a cached fallback if the source is briefly unreachable.
   resp = requests.get(
       f"{API_ORIGIN}/api/v1/mailboxes/{MAILBOX_ID}/messages",
       params={"direction": "inbound", "live": "true"},
       headers={"Authorization": f"Bearer {os.environ['SAIRAPH_MAIL_KEY']}"},
       timeout=30,
   )
   
   # { "object": "list", "data": [ … ], "has_more": …, "next_cursor": …, "url": … }
   # Rows discriminate on "object": "cached_message" vs "live_message".
   # Paginate by passing the returned next_cursor back as ?cursor=.
   messages = resp.json()["data"]

7. 07Wire the MCP server into your agent

   Point your MCP client at the endpoint with a mailbox key and the mailbox's actions become callable tools.

   claude_desktop_config.json

   {
     "mcpServers": {
       "sairaph-mail": {
         "type": "streamable-http",
         "url": "https://mail.sairaph.com/mcp/v1/mcp",
         "headers": {
           "Authorization": "Bearer ${SAIRAPH_MAIL_KEY}"
         }
       }
     }
   }

Start building