How to Get Started with testmail.app for Email Testing

Updated

testmail.app gives you unlimited real email addresses and mailboxes for automated email testing, and you can start on a free forever plan (100 emails/month) with no credit card required. You sign up, get a namespace and API key, then send test emails to {namespace}.{tag}@inbox.testmail.app and retrieve them via JSON or GraphQL API. This guide covers the setup steps, how the addressing scheme works, and how to integrate it into CI/CD.

What testmail.app Does

Instead of sending test emails to real customer inboxes, you route them to a catch-all address that testmail.app receives, parses, spam-tests, and indexes for retrieval through an API. Each tag you invent becomes a separate real email address and mailbox, so you can generate unlimited addresses on the fly without pre-registering them.

The core address format is:

{namespace}.{tag}@inbox.testmail.app
  • namespace — assigned to you at signup; identifies your account.
  • tag — anything you choose. Changing the tag creates a new address and mailbox.

Step 1: Sign Up and Get Your Namespace

Sign up on the site (the page states it takes about 30 seconds). You receive:

  • A namespace for your account.
  • An API key for authenticating API requests.

No credit card is required for the free forever plan, which covers 100 emails/month. If you need more volume or team features, check the pricing page for plan details.

Step 2: Send a Test Email

Point your application's email-sending code at an address built from your namespace and any tag:

[email protected]

Because the tag is arbitrary, you can create a unique address per test run — for example, using a timestamp or build ID as the tag — so parallel test runs don't collide.

Step 3: Retrieve Emails via API

testmail.app offers two query interfaces:

Interface Best for
JSON API Simple HTTP requests from any language or environment
GraphQL API More precise queries, interactive testing via the GraphQL Playground

You can use any HTTP or GraphQL client in any language, including inside CI/CD pipelines. Supported query features include:

  • Advanced search with wildcard match
  • "Live" queries that wait for new emails to arrive
  • Sorting and pagination
  • Attachments
  • SpamAssassin spam reports

For exact request formats and parameters, use the quickstart and API reference in the documentation.

Step 4: Integrate into CI/CD

The typical pattern:

  1. Your test suite triggers a signup or transactional email flow.
  2. The app sends to {namespace}.{tag}@inbox.testmail.app.
  3. Your test code calls the API (often with a live query) to fetch the email.
  4. Assert on the subject, body, links, or spam score.

Because retrieval is API-based, it fits any pipeline that can make HTTP requests — no mailbox UI or manual checking needed.

Verification and Common Pitfalls

  • Confirm the address format. A wrong namespace means the email never reaches your account.
  • Use unique tags per test. Reusing a tag mixes emails from different runs into one mailbox.
  • Prefer live queries over polling when you need to wait for delivery, to avoid timing flakiness.
  • Watch your monthly volume on the free plan (100 emails/month) if you run large suites.

Team and Security Notes

  • Invite team members by email; collaborators can be added on all plans at no extra cost, with separate namespaces/mailboxes per project, shared test emails, and usage monitoring.
  • Multiple separate teams are available on the enterprise plan.
  • HTTPS/TLS is forced on all traffic, data is encrypted in transit and at rest, and logins are passwordless.
  • APIs are distributed across multiple data centers with a stated 99.99% uptime SLA and a public status page.

Next Steps

Sign up to get your namespace and API key, read the quickstart, and try queries in the interactive GraphQL Playground before wiring the API into your test suite.