/reading-mailcatcher-api

name: reading-mailcatcher-api
description: Retrieves a link from Mailcatcher. Use when a local testing or debugging flow needs a link from an email, such as account verification links, magic-link logins, trial activations, organization invites, emergency access, and other email-driven flows. Preferred over the Mailcatcher browser UI in automation, where Playwright's CORS blocks a direct fetch. Do NOT use it to configure SMTP, start Mailcatcher, or debug delivery.
argument-hint: "--recipient <email> [--pattern <subject-keyword>] [--link-filter <regex>]"
allowed-tools: "Read(/${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/references/**), Bash(${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/scripts/read_mailcatcher.py:*), Bash(${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/scripts/get_admin_email.py:*)"

Reading the Mailcatcher API

Quick reference — use the script

For all programmatic uses (test runs, ad-hoc fetches, debugging), call the co-located script directly.

${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/scripts/read_mailcatcher.py --recipient <email> [--pattern <subject-keyword>] [--link-filter <regex>]

For example, to pull a verification link:

${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/scripts/read_mailcatcher.py --recipient testuser-s1@example.com --pattern "Verify"

• **`--pattern`** is optional; omit it to select the most recent message for the recipient
• **`--link-filter`** is optional; it defaults to `verify|confirm|signup|token|trial|login|finish-signup` — the starting filter that the exit-1 rows below may tell you to loosen or fix
• **stdout** (on success): the extracted URL, ready to navigate to or paste into a form field
• **exit code** (on failure): see the `read_mailcatcher.py` table below (the `get_admin_email.py` helper has its own codes, noted where it is introduced)

| Exit | Meaning | Correct response | | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 0 | matching URL printed on stdout | use it | | 1 | `NO_MATCH: no email for recipient …` — no matching message arrived (the script retried once after a 3s sleep) | if the email may not have arrived yet (a slow async send), re-invoke the script once more — a single fresh call, not a loop; the script's own 3-second retry supplies the delay. Otherwise the filters are too narrow: re-check `--recipient`, then widen or drop `--pattern`. | | 1 | matched a message, but no URL matched `--link-filter` (no retry; stderr: `matched but contained no URL filtered by …`) | the link is there but the filter missed it; loosen or fix `--link-filter` | | 1 | matched URLs, but none is on the local dev allowlist (no retry; stderr: `none of the N filter-matched URL(s) is a local dev host`) | stderr names the rejected host(s). This is an environment change outside the skill: ask the user to add the host to `MAILCATCHER_ALLOWED_HOSTS` in their shell (see Prerequisites), then retry. Do not prefix the assignment onto the script invocation — that falls outside the skill's Bash grant and re-prompts every call. | | 2 | usage error (bad or missing arguments) | fix the invocation | | 3 | Mailcatcher unreachable or returned invalid JSON | Mailcatcher is not running or unreachable. Starting it falls outside this skill's Bash grant: ask the user to start it (see Prerequisites), then retry. |

The script already retries once after a 3-second sleep on the first miss; callers don't need their own retry loop. See `${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatcher-api/references/manual-api-walkthrough.md` for the underlying Mailcatcher API the script wraps — consult it when modifying the script or debugging unexpected output.

A second granted helper, `${CLAUDE_PLUGIN_ROOT}/skills/reading-mailcatche