Giving the agent a real inbox it can read.

Auth flows need a real email round-trip.

Mailpit can't help here — the site's auth provider sends from its SMTP, not ours. The agent is a consumer of mail, not a producer. What we need is a disposable inbox with a read API.

How the round-trip closes.

The agent drives the browser (or HTTP client), Supabase/Clerk/Auth0 does its real thing, Mailosaur catches the outbound mail, and the agent reads it back. No local SMTP interception, no DNS tricks — auth provider config stays exactly as it runs in production.

graph LR
  A["AI Agent
(CLI + browser)"] -->|"1. signup form
email = run-42@xyz.mailosaur.net"| B["sitzio.de
auth UI"]
  B -->|"2. create user"| C["Auth Provider
(Supabase / Clerk / Auth0)"]
  C -->|"3. SMTP send
magic link"| D[("Mailosaur
MX records")]
  D -->|stores| E[["Inbox
@xyz.mailosaur.net"]]
  A -->|"4. GET /messages
?server=xyz&sentTo=..."| F{{"Mailosaur API
api.mailosaur.com"}}
  F -->|reads from| E
  F -.->|"5. JSON: body + links"| A
  A -->|"6. follow magic link"| B
  B -->|"7. user verified"| G(["✓ Auth flow passed"])

  classDef agent fill:#7c3aed,stroke:#a78bfa,color:#fff,stroke-width:2px
  classDef site fill:#1e293b,stroke:#22d3ee,color:#e2e8f0,stroke-width:2px
  classDef provider fill:#334155,stroke:#64748b,color:#e2e8f0,stroke-width:1.5px
  classDef mailosaur fill:#164e63,stroke:#22d3ee,color:#cffafe,stroke-width:2px
  classDef success fill:#365314,stroke:#a3e635,color:#ecfccb,stroke-width:2px

  class A agent
  class B site
  class C provider
  class D,E,F mailosaur
  class G success

Six steps the agent runs on every auth test.

Every step is a single CLI call or browser action. The unique-per-run address in step 1 is what keeps parallel test runs from stepping on each other.

What the agent actually calls.

Auth header on every request: Authorization: Basic $(echo -n api:$MAILOSAUR_API_KEY | base64). Replace $SERVER with your Mailosaur server ID.

Drop this into CLAUDE.md.

Once the agent has these three env vars and the protocol below, auth testing becomes a deterministic loop. No more "I assume the email was sent" hand-waving.

# Auth Testing — Mailosaur

# Mailosaur credentials — get from app.mailosaur.com
MAILOSAUR_API_KEY="<your api key>"
MAILOSAUR_SERVER_ID="<8-char id>"
MAILOSAUR_DOMAIN="${MAILOSAUR_SERVER_ID}.mailosaur.net"

# API base
MAILOSAUR_API=https://mailosaur.com/api

## Protocol for ANY auth-flow change on sitzio.de

  1. Mint a per-run address:
       EMAIL="run-$(date +%s)-$(openssl rand -hex 3)@$MAILOSAUR_DOMAIN"

  2. Submit signup / login form with $EMAIL

  3. Await the verification mail (blocks up to 10s):
       curl -s -u "api:$MAILOSAUR_API_KEY" \
         "$MAILOSAUR_API/messages/await?server=$MAILOSAUR_SERVER_ID&sentTo=$EMAIL"

  4. Parse the response — use message.html.links[0].href
     (or message.html.codes[0].value for OTPs)

  5. Follow the link / submit the code, then assert the
     authenticated session exists (cookie, /me returns 200, etc.)

  6. Clean up:
       curl -X DELETE -u "api:$MAILOSAUR_API_KEY" \
         "$MAILOSAUR_API/messages?server=$MAILOSAUR_SERVER_ID"

  RULES:
  - NEVER use a hardcoded email for auth tests — always mint a fresh one.
  - NEVER skip step 5; SMTP acceptance != user verified.
  - If await times out, the auth provider's SMTP config is broken — report, don't retry blindly.

Free tier covers our use case.

One server, 500 emails/month. An auth test burns ~1–3 emails (signup + maybe password reset). That's ~150–500 test runs a month on zero dollars.