AI agents

MailAgent gives agents a disposable inbox, waits for verification email, and returns what to do next — OTP code or magic link with plain-language instructions.

Recommended: verify signup

POST /v1/agent/verify
Authorization: Bearer <API_KEY>

{
  "service": "github",
  "timeoutSeconds": 90,
  "deleteAfter": true
}

Response includes email.address (use on signup form) and agent.primaryAction:

{
  "status": "verified",
  "email": { "inboxId": "…", "address": "inbox-abc@…" },
  "verification": { "otp": "123456", "primaryLink": "https://…" },
  "agent": {
    "primaryAction": {
      "type": "otp",
      "value": "123456",
      "instruction": "Enter this code in the verification field…"
    }
  }
}

Two-step flow

  1. POST /v1/agent/verify with only service → get email.address
  2. Agent submits address on external signup form
  3. POST /v1/agent/verify with inboxId → get primaryAction

Or one-shot: create + wait in a single call after the user submitted the form.

MCP (Cursor)

Tool: mailagent_verify_signup — same as REST verify.

{
  "mcpServers": {
    "mailagent": {
      "command": "node",
      "args": ["mcp/dist/index.js"],
      "envFile": ".env"
    }
  }
}

Build: npm run build:mcp. Skill: skills/mailagent/SKILL.md (synced to Cursor/Codex)

Agent Skills install

npx skills add Alex0nder/MailAgent --skill mailagent

Canonical skill at repo root skills/mailagent/ — Agent Skills guide. After signup verify, use app-specific skills (e.g. Membrane github, slack) for post-login actions.

OpenAI Codex

Same MCP tools via plugin or ~/.codex/config.toml — Codex install guide. 

# ~/.codex/config.toml
[mcp_servers.mailagent]
command = "npx"
args = ["-y", "-p", "@mailagent/mcp@0.2.5", "mailagent-mcp"]

[mcp_servers.mailagent.env]
MAILAGENT_API_URL = "https://api.webmailagent.com"
MAILAGENT_API_KEY = "your_key"

Plugin scaffold: examples/codex/plugin · Remote MCP: use POST https://api.webmailagent.com/mcp (see below).

CLI

npm run build:mcp
MAILAGENT_API_URL=https://api.webmailagent.com \
MAILAGENT_API_KEY=ma_… \
  npx mailagent verify --service github --json

Service recipes

GET /v1/agent/recipes
GET /v1/agent/recipes/github

Presets: github, google, dribbble, stripe, auth0, figma, notion, linear, slack, … — see GET /v1/agent.

Remote MCP (hosted)

No local subprocess — connect agents directly to the API.

JSON-RPC (stateless)

POST https://api.webmailagent.com/mcp
Authorization: Bearer <API_KEY>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Streamable HTTP (sessions)

initialize → response header Mcp-Session-Id. Subsequent requests include that header. SSE channel: GET /mcp with Accept: text/event-stream. End session: DELETE /mcp. 

POST /mcp  method: initialize
→ Mcp-Session-Id: mcp_…

POST /mcp  Mcp-Session-Id + tools/call
GET  /mcp  Mcp-Session-Id + Accept: text/event-stream
DELETE /mcp  Mcp-Session-Id

Auth meta: GET /mcp/auth. Smoke: npm run smoke:agent

OAuth (client_credentials)

MCP clients can discover auth via RFC 9728 and exchange API key for short-lived mat_ token.

GET /.well-known/oauth-protected-resource/mcp
GET /.well-known/oauth-authorization-server

POST /v1/oauth/token
grant_type=client_credentials&client_secret=<API_KEY>
→ { "access_token": "mat_…", "expires_in": 3600 }

DCR (RFC 7591): register a dedicated MCP client key with team API key:

POST /v1/oauth/register
Authorization: Bearer <TEAM_API_KEY>
{ "client_name": "cursor-mcp" }
→ { "client_id": "mac_…", "client_secret": "ma_…" }

GET /v1/oauth/clients/:id  (metadata, no secret)

401 on /mcp includes WWW-Authenticate with resource metadata URL.

Full guide: MCP OAuth (Auth0 / Google) · MCP-OAUTH.md

Scoped keys for agents & CI

Restrict MCP and REST keys so they only touch inboxes whose label starts with a prefix (e.g. agent-{runId}). Optional readOnly blocks create/delete — useful for extract-only automation. 

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

POST /v1/oauth/register
{ "client_name": "cursor-mcp", "scope": { "labelPrefix": "agent-", "readOnly": true } }

Scoped keys guide →

Progress while waiting

Wait tools stream notifications/progress when Accept: text/event-stream on tools/call.

POST /mcp  Accept: text/event-stream
tools/call mailagent_wait_for_message

→ SSE: notifications/progress (elapsed/total)
→ SSE: final tools/call result

With Mcp-Session-Id, progress also relays on GET /mcp SSE. Guide: docs/MCP-PROGRESS.md

Call a tool:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "mailagent_verify_signup",
    "arguments": { "service": "github", "runId": "cursor-session-42" }
  }
}

runId → label agent-{runId} for tracing via GET /v1/inboxes?label=agent-… or Agent runs UI.

SDK

TypeScript / Node

npm install @mailagent/agent

import { MailAgent } from "@mailagent/agent";
const mail = new MailAgent({ baseUrl, apiKey });
const { access_token } = await mail.fetchMcpAccessToken();
const { sessionId } = await mail.connectMcp(undefined, access_token);
await mail.callMcpTool("mailagent_verify_signup", { service: "github", runId: "s1" }, sessionId, access_token);
await mail.verifySignup({ service: "github", runId: "session-1" });

Python

pip install mailagent-agent

from mailagent import MailAgent

client = MailAgent("https://api.webmailagent.com", "ma_…")
result = client.verify_signup(service="github", timeout_seconds=90, delete_after=True)
print(result.get("agent", {}).get("primaryAction"))

PyPI: mailagent-agent · source: packages/mailagent-agent-py

QA (Playwright / Cypress)

npm install @mailagent/qa

import { createMailAgentQa } from "@mailagent/qa";
const mail = createMailAgentQa();
await mail.simulateAndVerify(inboxId, { scenario: "magic_link" });

Raw MIME & attachments

When agent.primaryAction.type is manual, use archived .eml or attachments:

MCP v0.7: 12 tools — list/get attachments, list/get raw
mailagent_list_messages → mailagent_get_raw_message | mailagent_list_attachments

REST: GET …/messages/:messageId/raw
      GET …/messages/:messageId/attachments[/:attachmentId]

Verify: hasRaw, rawUrl, hasAttachments, attachmentCount

Attachments guide →

Outbound send & reply

Two-way agent mail: POST …/send, POST …/reply, threads, console UI. Requires Resend + optional OUTBOUND_FROM on a verified domain.

Outbound setup guide →

Autotests

Agents and CI verify prod without real SMTP — contract tests use POST …/simulate. Same gate as GitHub Actions: 

MAILAGENT_API_URL=https://api.webmailagent.com \
MAILAGENT_API_KEY=ma_… \
  npm run test:prod

Autotests guide → · GET /v1/agent returns tests and autotests URLs.

Security