Confirmations and alerts your agents can send safely
When an agent finishes a task, it often needs to tell someone — a receipt, a status, an alert. Send from a managed domain with automatic DKIM, an idempotency key so retries never double-send, and per-mailbox suppression so deliverability holds.
# Pass a unique Idempotency-Key on every mutating call so a retried request
# can never send the same email twice. On send the header is REQUIRED — the
# request is rejected without it.
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."
}'An idempotent send — a retried request won't double-execute.
Agents retry — and naive sending double-sends
Autonomous code retries on timeouts and partial failures. With a plain send endpoint, a retry means the customer gets two receipts, or ten. Then there's deliverability: mail from a fresh, unauthenticated domain lands in spam, and a few bounces or complaints can tank the whole domain's reputation. You need idempotent sends, a domain that's already authenticated, and automatic suppression of addresses that bounce or complain.
How it works
01Send from a managed domain
Register a domain (first-year registration is covered by your plan's domain credit) or connect one; DKIM is set up automatically and outbound goes through the SES relay in eu-west-1.
02Make every send idempotent
Pass an Idempotency-Key header on the send so a retried request doesn't double-execute.
cURL# Pass a unique Idempotency-Key on every mutating call so a retried request # can never send the same email twice. On send the header is REQUIRED — the # request is rejected without it. 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." }'03Handle structured errors
Errors come back in a consistent, Stripe-shaped envelope you can branch on programmatically.
JSON{ "error": { "type": "resource_not_found", "code": "mailbox_not_found", "message": "No mailbox matches that id.", "param": "mailbox_id" } }04Respect rate limits
Each key is rate-limited per minute, scaled by plan; exceed it and you get a 429 with a Retry-After header to back off cleanly.
05Let suppression protect the domain
Addresses that bounce or complain are suppressed per mailbox, so future sends don't keep hitting dead or hostile recipients.
Send it safely
An idempotent send over cURL, the same call over the SDK-free fetch path, and the error shape you branch on.
# Pass a unique Idempotency-Key on every mutating call so a retried request
# can never send the same email twice. On send the header is REQUIRED — the
# request is rejected without it.
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."
}'Idempotent writes, Stripe-shaped errors.
What this leans on
The capabilities behind reliable agent sending.
- Managed domain, DKIM & deliverability
- REST API
- Scoped, expiring API keys
- EU data residency
- Native MCP server
Frequently asked questions
Related
Send from a domain that's ready
DKIM, idempotency, and suppression handled for you.
EU data residencyPer-customer encryptionNative MCP