InboxTap

Getting started

Introduction

What InboxTap captures, why it exists, and where it is safe to run.
Maintained by contributorsLast updated

InboxTap is a local email capture server and TypeScript SDK for automated tests. Use it when a Playwright, Cypress, Vitest, Jest, or Bun test needs to retrieve a verification link, magic link, password-reset link, invitation, one-time code, or another value from a real email generated by the application under test.

InboxTap runs on localhost without Docker, accepts the application's SMTP message, and exposes the captured result to the test through a typed SDK or HTTP API. It is not a production email provider, hosted inbox, deliverability service, persistent mail store, or manual email preview interface.

Key facts

  • Messages stay on the local machine and are never relayed externally.
  • Client-generated recipient addresses isolate parallel tests without server-side registration.
  • The package runs through npx or bunx and supports Node 20 and later.
  • Storage, message sizes, list results, and wait times all have explicit bounds.

Why InboxTap?

Email flows sit at an awkward boundary in end-to-end tests. Mocking the mail sender skips the output your user would receive, while a hosted mail service adds accounts, network latency, and real inboxes to a test that should be deterministic.

InboxTap keeps that boundary local. It accepts arbitrary recipients, parses the delivered message, and exposes the result to the same test that triggered the email.

How it works

  1. Start InboxTap locally or alongside your test process.
  2. Point the application under test at localhost:1025.
  3. Give the application a unique address created by InboxTapClient.
  4. Await the expected value through the SDK or query the local HTTP API.

Captured messages include the SMTP envelope, normalized headers, decoded text and HTML, discovered HTTP(S) links, unique 4–8 digit codes, and the raw RFC 822 source.

Safety and scope

InboxTap binds SMTP and HTTP only to the loopback addresses (127.0.0.1 and ::1) by default and never relays a message externally. It is for development and automated tests, not for production mail delivery.

The v1.4.1 server stores messages in memory, retains the newest 100 by default, rejects messages over 5 MiB by default, and caps HTTP long-poll waits at 60 seconds. It does not provide persistence, a browser inbox, attachments workflow, webhooks, SMTP authentication, or STARTTLS.