MCP wait_for_email

wait_for_email waits until a matching message arrives or the timeout expires. It is read-only and requires access to the target inbox.

Input

{
  "inbox": "pmbx_...",                 // required: opaque id or project-local address
  "from": "no-reply@acme.test",      // optional sender substring
  "subject": "verification",         // optional subject substring
  "regex": "(?i)code",               // optional Go RE2 expression
  "link_hint": "verify",             // optional URL preference, not a match filter
  "since_now": true,                  // default: ignore earlier messages
  "timeout_ms": 120000                // default 120s, maximum 600s
}

regex is case-sensitive unless it includes (?i). The MCP server sends it to the REST match field. link_hint biases verification-link extraction after a message matches.

Matched result

{
  "matched": true,
  "message": {
    "id": "msg_8Tz",
    "thread_id": "thr_9aB",
    "inbox": "support@extrovertmail.com",
    "direction": "inbound",
    "from": { "email": "no-reply@acme.test" },
    "subject": "Verify your email",
    "text": null,
    "html": "<p>Your code is <strong>492013</strong></p>",
    "extracted_text": null,
    "extracted_html": "<p>Your code is <strong>492013</strong></p>",
    "folder": "INBOX",
    "seen": false
  },
  "otp_code": "492013",
  "verification_link": "https://acme.test/verify?token=...",
  "waited_ms": 8421
}

On timeout, the tool returns matched: false with waited_ms. This is a normal result. The agent can retry, extend the timeout, or trigger another verification email.

Body fields

The structured message preserves source MIME alternatives:

text is source plain text and may be null.
html is source HTML and may be null.
extracted_text and extracted_html are nullable, best-effort derivatives.

The server does not synthesize one source format from the other. The top-level otp_code and verification_link are credential extraction results, not replacements for the message body fields.

Use get_message with variant: "source" when exact content matters. Use variant: "extracted" for a concise presented body when quote and signature removal is acceptable. The structured result keeps the separate fields in either case.

Timeouts and matching

since_now: true matches only messages that arrive after the wait starts. Set it to false when an already-delivered message is acceptable.

Keep the wait budget close to the external workflow’s actual expiry. Custom MCP transports and proxies must allow a read timeout longer than timeout_ms; the packaged server already does.