Local auth testing without the flaky inbox dance

Why auth tests are so fragile

Your test suite signs up a user. The app sends an email verification code, then a text-message 2FA code. The whole thing should take seconds, but it often turns into waits, retries, inbox scraping, and one very suspicious timeout.

• Cloud sandboxes add coupling

  Mailtrap, SendGrid, and phone-verification SaaS reduce the blast radius, but your local suite still depends on the network, API keys, account state, and a pricing tier.

• Classic catchers are email-only

  MailHog and Mailpit are great SMTP catchers, but they stop at email. Modern auth testing needs SMS, OTP extraction, magic links, and clean wait APIs too.

• Agents hit a wall at OTPs

  An autonomous agent can't casually read a phone or browse webmail like a patient human. It needs a native, structured channel for email and SMS.

Everything you need, nothing you don't

Four capabilities that make Postwire feel boring in the best developer-product sense: predictable, local, scriptable, and easy to delete from your mental stack.

How it works

One binary, two channels, one long-polling engine. Point your app at the listeners — your tests and agents just wait and read.

1. 01

   Point your app at Postwire

   SMTP relay on localhost:1025 , Twilio webhook on /api/sms/webhook . No keys, no sandbox account.

2. 02

   It catches and parses everything

   Both channels land in SQLite, and codes, magic links, and reset URLs come out already extracted — no parsing code in your test.

3. 03

   Your test or agent waits, then reads

   Long-poll /api/wait , read the signal, keep going. No sleep() , no polling loop, no flake.

Running locally in under 30 seconds

Same binary, several install paths. Start with Docker, Homebrew, Cargo, or the one-liner and point your app at localhost:1025 .

docker run -d --name postwire \
  -p 1025:1025 -p 8025:8025 \
  yoosuf/postwire:latest

brew tap yoosuf/tap
brew install postwire

curl -fsSL https://raw.githubusercontent.com/\
yoosuf/postwire/main/install.sh | sh

cargo install --git \
  https://github.com/yoosuf/postwire \
  postwire-server postwire-mcp

Built for AI agents

A native Model Context Protocol (MCP) server exposes the whole local inbox as 14 tools — 7 for email, 7 for SMS. An agent can complete signup, email verification, password reset, and SMS 2FA without touching a browser inbox.

{
  "mcpServers": {
    "postwire": {
      "command": "postwire-mcp",
      "env": {
        "POSTWIRE_URL": "http://localhost:8025"
      }
    }
  }
}

Fourteen tools across email and SMS, grouped by what an agent actually needs to do. An agent signs up, waits for the confirmation email, pulls the code or link out of it, reads the second factor, and keeps going — no inbox to click through.

• wait

  wait

  wait_for_emailandwait_for_smsblock until a matching message lands on either channel and hand it straight back. They resolve the moment the message arrives rather than on a poll interval, and give up on timeout instead of leaving the agent hanging.

• extract

  extract

  extract_signalsandextract_sms_signalspull verification codes and links out of the raw body, so nobody has to write a parsing regex. They recognise 4–8 digit numeric and alphanumeric OTPs, magic login links, password reset URLs and confirmation triggers.

• read

  read

  list_emails,get_email,list_smsandget_smsare for taking inventory before you wait. The list calls return headers and metadata without dragging the whole HTML body along; the get calls fetch one message when you actually need it.

• clear

  clear

  send_test_emailandsend_test_smsput a message into the local inbox, so you can drive a two-factor fixture from both ends.delete_email,delete_sms,clear_inboxandclear_sms_inboxreset either channel on its own between runs.

In your test suite

Deterministic, race-free, and fast. If delivery fails, the test fails on a clean timeout — it never hangs and never waits on someone else's API.

const since = new Date().toISOString();   // capture BEFORE triggering

await fetch("http://localhost:3000/api/signup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "[email protected]", password: "..." }),
});

const email = await (await fetch(
  `http://localhost:8025/api/[email protected]&since=${since}&timeout_ms=10000`
)).json();

const { codes } = await (await fetch(
  `http://localhost:8025/api/messages/${email.id}/extract`
)).json();

await fetch("http://localhost:3000/api/verify-email", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "[email protected]", code: codes[0] }),
});
console.log("verified with code", codes[0]);

Postwire vs. MailHog, Mailpit, and Mailtrap

Honest comparison. MailHog and Mailpit are still useful. Mailtrap is polished. Postwire is built for the local auth-testing jobs they were never quite designed to own.

Developer guide

Plain HTTP with JSON responses on localhost:8025 . No SDK, no auth, no API keys — just curl, or whatever your test suite already speaks.

• <15 MB

  Single binary

• <5 ms

  Startup time

• 2

  Channels: email + SMS

• 14

  MCP tools for AI agents

Frequently asked questions