Mailagent

MailAgent

MailAgent provides programmatic disposable inboxes for AI agents: receive OTP codes and magic links during signup flows, simulate inbound mail in CI, send/reply on verified domains, and diagnose timeouts.

Official docs: https://webmailagent.com/docs/agents.html

When to use

• Signup or login that sends a verification email
• Need OTP or magic link without hand-parsing HTML
• E2E / agent task: "register with a temp email"
• QA without real SMTP (mailagent_simulate_message)
• Not for human privacy burners — programmatic agent inboxes with allowlists

Install (pick one)

Cursor (project)

MCP in .cursor/mcp.json → @mailagent/mcp or mcp/dist/index.js. Skill auto-loads from .cursor/skills/mailagent-mcp/ (synced from this file).

Agent Skills catalog (repo root)

npx skills add Alex0nder/MailAgent --skill mailagent

OpenAI Codex

codex plugin marketplace add Alex0nder/MailAgent
codex plugin add mailagent@mailagent

Guide: https://webmailagent.com/docs/codex.html

npm MCP (any client)

export MAILAGENT_API_URL=https://api.webmailagent.com
export MAILAGENT_API_KEY=ma_…
npx -y -p @mailagent/mcp@0.2.16 mailagent-mcp

Remote (no subprocess): POST https://api.webmailagent.com/mcp + Bearer token.

SDK (without MCP)

Browser login (no API key in client): Auth0 OIDC on prod — auth.oidc: enabled on GET /v1/agent. Operator setup: npm run wizard:auth0. Docs: https://webmailagent.com/docs/oauth-idp.html

Prerequisites

• MAILAGENT_API_KEY — console dashboard team keys, or MailAgent repo npm run issue:key:db when self-hosting
• MCP server mailagent connected (codex mcp list / Cursor MCP refresh)
• Always set service preset or expectFrom (sender allowlist)

If you are unsure what to do next, call mailagent_plan_next first. It returns nextTool, nextPayload, recovery steps, and ready payloads for create/verify/diagnose/simulate.

If sender or subject is unclear, call mailagent_suggest_preset with a sample from / subject. Use its returned service, or use returned expectFrom when knownPreset=false.

Recommended flow

If you have an unrestricted team key and need to hand a run to a sub-agent, call mailagent_issue_access first with runId or labelPrefix. Use the returned short-lived key only for that run; all inbox labels must start with the returned labelPrefix.

For autonomous multi-step QA, call mailagent_start_run before browser work. Execute plan.nextTool, call mailagent_report_run after each form submit/wait/failure, and call mailagent_next_run to resume after context loss.

Primary: mailagent_verify_signup → returns agent.primaryAction (otp | magic_link, value, instruction).

Two-step (preferred for browser automation):

1. mailagent_create_inbox — use address on the signup form
2. mailagent_verify_signup with inboxId — wait + extract + primaryAction

REST equivalent: POST /v1/agent/verify

Login 2FA / password reset

Same tools — set flow when subjectContains is omitted:

{ "inboxId": "…", "service": "github", "flow": "login" }

Recipes: GET /v1/agent/recipes/github?flow=login · simulate: scenario=login_2fa or password_reset.

Async verify (callbackUrl)

When the test runner has a public HTTPS endpoint, prefer callback over long poll:

1. mailagent_create_inbox with callbackUrl (smee.io, staging hook, CI tunnel)
2. Submit form → MailAgent POSTs verification JSON to your URL
3. @mailagent/qa: waitForCallback(inboxId) — or poll GET …/callbacks

Do not use callback for Cursor agents without a reachable URL — use verify_signup poll instead.

Developer relay (notifyEmail)

Manual QA only — OTP summary to your real Gmail while the temp address is on the signup form:

{ "service": "github", "notifyEmail": "you@company.com" }

SDK: createInbox({ notifyEmail }) · @mailagent/qa: waitForNotifyDelivery(inboxId) after mail arrives. Console: console-inbox.html → notify relay log.

Popular MCP tools

Full list: GET https://api.webmailagent.com/v1/agent → mcpTools (44 tools).