Local auth testing without the flaky inbox dance

Why developers switch to Pine Mail

It replaces the messy parts of auth testing with one local tool: email testing, SMS 2FA testing, webhook capture, OTP extraction, and agent-readable APIs in the same process.

• For local dev

  A MailHog and Mailpit alternative that understands modern auth

  Catch SMTP like the classic tools, then go further: parse verification codes, magic links, reset URLs, and SMS messages without asking your app or your browser to pretend.

• For E2E and CI

  Deterministic Playwright auth tests with zero sleep()

  Long-polling waits return when the matching email or text arrives. Use since , assert the extracted code, clean the inbox, and keep the pipeline boring.

• For AI agents

  MCP-native email and SMS tools for full MFA flows

  Agents can wait for email, extract a link, wait for SMS, read the OTP, and finish login through 14 structured MCP tools instead of screen-scraping webmail.

The problem: auth testing is still too 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.

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. 1

   Point your app at Pine Mail

   SMTP relay at localhost:1025 ; Twilio webhook at /api/sms/webhook .

2. 2

   It catches and parses everything

   Stores messages in SQLite and extracts codes, magic links, and reset URLs automatically.

3. 3

   Your test or agent waits, then reads

   Long-poll /api/wait or /api/sms/wait , pull the OTP, keep going. Zero sleep().

Everything you need, nothing you don't

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

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.

Pine Mail vs. MailHog, Mailpit, and Mailtrap

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

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 pinemail \
  -p 1025:1025 -p 8025:8025 \
  yoosuf/pinemail:latest

brew tap yoosuf/tap
brew install pinemail

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

cargo install --git \
  https://github.com/yoosuf/pinemail \
  pinemail-server pinemail-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": {
    "pinemail": {
      "command": "pinemail-mcp",
      "env": {
        "PINEMAIL_URL": "http://localhost:8025"
      }
    }
  }
}

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]);

• <15 MB

  Single binary

• <5 ms

  Startup time

• 2

  Channels: email + SMS

• 14

  MCP tools for AI agents

Frequently asked questions