API documentation

MailAgent is open source — GitHub. Self-host or use hosted API at https://api.webmailagent.com with Authorization: Bearer <API_KEY>. Get a key in the Dashboard (no signup — API key only). Gmail/Calendar workspace: Workspace.

Discovery

GET /v1

Returns endpoints, service presets, MCP tool names. Try it (requires API key).

Recommended: one-shot open

POST /v1/inboxes/open
{
  "service": "github",
  "label": "ci-123",
  "subjectContains": "verification",
  "timeoutSeconds": 90,
  "deleteAfter": false
}

Creates inbox → waits for allowed email → returns verification.otp and verification.primaryLink.

Step-by-step flow

Method	Path	Description
`POST`	`/v1/inboxes`	Create inbox (`ttlMinutes`, `service`, `label`, `callbackUrl`)
`GET`	`/v1/inboxes?label=`	List inboxes for a CI run
`GET`	`/v1/inboxes/:id/wait`	Wait for message (`subjectContains`, `timeout`)
`GET`	`/v1/inboxes/:id/extract`	OTP + links from latest message
`GET`	`/v1/inboxes/:id/messages/:msgId/raw`	Full .eml from R2 (`hasRaw` on list)
`GET`	`/v1/inboxes/:id/messages/:msgId/attachments`	List attachments (`attachmentCount` on list)
`GET`	`/v1/inboxes/:id/events`	SSE stream
`DELETE`	`/v1/inboxes/:id`	Delete inbox

Service presets

Set service to apply sender allowlists: github, stripe, auth0, google, vercel, supabase, clerk, and others — see GET /v1 for the full list.

Scoped API keys

Limit CI and agent keys with labelPrefix and optional readOnly. Create via POST /v1/team/keys (admin key) or DCR with scope. GET /v1/me returns your current scope.

POST /v1/team/keys
{ "label": "ci-bot", "scope": { "labelPrefix": "ci-", "readOnly": false } }

Scoped keys guide →