Open source

API documentation

MailAgent is open source — GitHub. Self-host or use hosted API at https://api.webmailagent.com with Authorization: Bearer <API_KEY>.

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

MethodPathDescription
POST/v1/inboxesCreate inbox (ttlMinutes, service, label, callbackUrl)
GET/v1/inboxes?label=List inboxes for a CI run
GET/v1/inboxes/:id/waitWait for message (subjectContains, timeout)
GET/v1/inboxes/:id/extractOTP + links from latest message
GET/v1/inboxes/:id/eventsSSE stream
DELETE/v1/inboxes/:idDelete 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.

More

Self-host: clone the repo and follow SETUP in README. Hosted API: hello@webmailagent.com for a key.