Quickstart

Deploy mail-catcher and receive your first email in 5 minutes.

Get mail-catcher running in your AWS account with minimal configuration.

Prerequisites

  • Bun installed
  • SST v4 installed globally (npm i -g sst)
  • AWS account with credentials configured
  • A domain or subdomain you control

1. Clone and install

git clone https://github.com/rodavel-labs/mail-catcher.git
cd mail-catcher
bun install

2. Configure

cp .env.example .env

Set the required values:

AWS_PROFILE=default
AWS_REGION=us-east-1
SES_DOMAIN=receive.yourdomain.com

Region constraint: SES inbound email only works in us-east-1, us-west-2, and eu-west-1.

If your domain is on Route 53, add HOSTED_ZONE_ID for automatic DNS setup. Otherwise, you'll configure DNS manually after deploying.

3. Deploy

bun run deploy:dev

The deploy output includes your API URL and the DNS records you need to add.

4. Set up DNS records (external DNS only)

Skip this step if you set HOSTED_ZONE_ID in your .env. The MX and TXT records are created automatically via Route 53.

If you're managing DNS externally (Cloudflare, Namecheap, etc.), SES needs two records to receive emails on your domain:

  • MX record on receive.yourdomain.com → 10 inbound-smtp.<region>.amazonaws.com
  • TXT record on _amazonses.receive.yourdomain.com → <token from deploy output>

The deploy writes the exact values to .sst/dns-records.zone. Add them in your DNS provider and wait for the domain to show as Verified in the SES Console before continuing.

See the Deployment guide for full details.

5. Create an API key

bun run provision --create --name my-key

Save the token. It's shown once and can't be retrieved again.

6. Send a test email

Send any email to test@receive.yourdomain.com, then query the API:

curl -H "Authorization: Bearer <your-token>" \
  "<api-url>/v1/emails?inbox=test&wait=true"

The wait=true parameter makes the API poll until an email arrives (up to 28 seconds).

You can also explore the API interactively by visiting <api-url>/docs in your browser. This opens a Scalar-powered playground with all available endpoints.

Next steps

Search Documentation

Search through the docs