Send and receive in a few steps

The fastest path from signup to a working mailbox: provision it, issue a scoped key, POST once to send, GET once to read inbound, connect MCP. You need an account to issue keys, so start there.

Step by step

1. 01Verify your email

   Browse the dashboard right after signup. Ordering a domain, creating a mailbox, and sending are gated on a verified email.

2. 02Order a domain

   Register your domain from the dashboard. Your first year is covered by your plan's domain credit.

3. 03Provision a mailbox

   Provisioned on OVH against your verified domain. This is the mailbox your agent owns.

4. 04Issue a scoped API key

   In the dashboard: API keys, pick the mailbox, a role (read, read_write, or management), and an optional expiry. Copy the sm_live_ secret; it is shown once. Set it as SAIRAPH_MAIL_KEY. The same key authenticates REST and MCP.

5. 05Send with one POST

   One POST sends from your mailbox over /api/v1. The Idempotency-Key header is required, so a retried request never sends the mail twice. You get back a 202 with a message id.

   cURL

   Show example

   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

   Show example

   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 with one GET

   One GET lists inbound messages. Add live=true for an on-demand IMAP fetch with a cached fallback. The response is a list envelope; paginate by passing next_cursor back as ?cursor=.

   cURL

   Show example

   # 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

   Show example

   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. 07Connect the MCP server

   Point your MCP client at /mcp/v1/mcp with the same mailbox key. The mailbox's actions become callable tools over streamable-HTTP.

   claude_desktop_config.json

   Show example

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

Start building