Manual API Walkthrough

Every command here needs a fresh permission prompt. This skill’s allowed-tools grants only the co-located script.

Prerequisite check

Verify Mailcatcher is reachable before working through the steps below:

Step-by-Step Workflow

Step 1 — List all messages

Returns a JSON array of message objects:

Step 2 — Find the target message

Filter by recipient email and/or subject keyword and select the highest ID (most recent):

Handle both outcomes before proceeding:

• NO_MATCH — no matching email yet; read_mailcatcher.py retries once after a 3 s sleep (RETRY_DELAY), so when stepping through by hand, wait ~3 s and retry once — if it is still missing, the message has most likely not been sent
• A numeric ID — proceed to Step 3

When filtering:

• Match on recipient email when the test account address is known (preferred)
• Match on subject keyword when recipient is generic/unknown
• Always take max(id) — higher ID = more recent message

Step 3 — Fetch the message body

For link/token extraction, plain text is usually sufficient and easier to parse:

<message-id> is the numeric id from Step 2. Substitute it into each command below: every block runs in a fresh shell, so a value set in one does not carry into the next.

Use .html only when the plain text body is empty or the link is only in the HTML part:

Step 4 — Extract the link or token

Extract any URL matching a keyword pattern:

Extract an admin magic link:

Extract a web vault verification/signup link:

Message metadata and deletion (debugging only)

Fetch a message’s raw JSON metadata (id, recipients, subject, available formats):

The two commands below are destructive and irreversible. Clearing the inbox mid-run destroys verification tokens that earlier test steps depend on. They are not covered by this skill’s allowed-tools, so each requires a fresh permission prompt.