Overview

What mail-catcher is, who it's for, and how it works.

What is mail-catcher?

mail-catcher is a serverless inbound email API built on AWS. It receives emails via Amazon SES, stores them in S3 and DynamoDB, and gives you a simple REST API to query and retrieve them.

It's designed for two primary use cases:

  • E2E testing: your app sends emails (verification codes, notifications, invites) and your tests need to confirm they arrived with the right content.
  • Email ingestion pipelines: you need a lightweight way to receive and process inbound emails without running a mail server.

How it works

Sender → Email → SES (catch-all rule)
                     ↓
                 S3 Bucket (raw .eml)
                     ↓
              Ingest Lambda (parse)
                     ↓
               DynamoDB (metadata)
                     ↓
              REST API (query emails)
  1. Receive: Amazon SES receives emails on your configured domain and stores the raw .eml file in S3.
  2. Parse: An S3 event triggers the Ingest Lambda, which parses the email (headers, body, attachments) and writes metadata to DynamoDB.
  3. Query: Your application calls the REST API to list, filter, and retrieve emails by inbox. Long-polling is supported for real-time waiting.
  4. Cleanup: Emails auto-expire after 7 days (DynamoDB TTL) and raw files after 8 days (S3 lifecycle).

Who is this for?

  • QA engineers writing E2E tests that verify email delivery
  • Backend developers building email-triggered workflows
  • DevOps engineers setting up shared email testing infrastructure
  • Solo developers who need a simple, self-hosted email inbox API

Key features

  • REST API: list, filter, retrieve, and delete emails via simple HTTP endpoints.
  • Long-polling: pass wait=true to block until an email arrives, avoiding polling loops in tests.
  • Interactive API docs: visit GET /docs on your deployed API for a Scalar-powered playground where you can explore and test endpoints.
  • Attachment support: attachments are parsed and stored separately, downloadable via pre-signed S3 URLs.
  • Bearer token auth: API keys are SHA-256 hashed at rest. Create, list, and revoke keys via a CLI tool.
  • Ephemeral by default: emails auto-expire after 7 days. This is a testing tool, not an email archive.

Design principles

  • Deploy once, use everywhere: one SES domain and one API shared across all your projects.
  • Serverless: no servers to manage. Runs entirely on Lambda, S3, DynamoDB, and SES.
  • Self-contained: deploy as a standalone repo or merge into an existing monorepo.

Next steps

Search Documentation

Search through the docs