API reference · v1

Planned contract for the Mailrail REST API. The API is not live yet; examples use placeholder hosts.

Authentication

Send your secret key as a bearer token. Keys are scoped to one application and environment. Never expose them in browser code.

Authorization: Bearer <your-api-key>

Endpoints

GET/v1/mailboxesList connected mailboxes
POST/v1/mailboxes/connectStart a Gmail or Microsoft 365 OAuth connection
DELETE/v1/mailboxes/{id}Disconnect a mailbox and revoke tokens
GET/v1/messagesList messages (cursor pagination)
GET/v1/messages/{id}Retrieve a message
POST/v1/messages/sendSend a message from a mailbox
GET/v1/threads/{id}Retrieve a thread
GET/v1/webhooksList webhook endpoints
POST/v1/webhooksCreate a webhook endpoint

Send a message

curl https://api.mailrail.example/v1/messages/send \
  -H "Authorization: Bearer $MAILRAIL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c..." \
  -d '{"mailbox_id":"mbx_1","to":["anna@example.com"],"subject":"Hello","text":"Hi Anna"}'

Webhook events

Payloads are signed with HMAC-SHA256 in the Mailrail-Signature header. Failed deliveries retry with exponential backoff for up to 24 hours.

{ "id": "evt_19ab", "type": "message.received", "created_at": "2026-11-13T09:58:11Z",
  "data": { "mailbox_id": "mbx_1", "message_id": "msg_8f2c" } }

Errors

{ "error": { "type": "rate_limited", "message": "Too many requests", "request_id": "req_7c1d" } }
400 invalid_request · 401 unauthenticated · 403 forbidden · 404 not_found · 409 conflict · 429 rate_limited · 5xx provider_error