Installation

Prerequisites, setup steps, and project structure.

Prerequisites

Bun: package manager and runtime
SST v4: npm i -g sst
AWS account with credentials configured (~/.aws/credentials or environment variables)
A domain or subdomain you control for receiving emails

Region constraint: SES inbound email is only available in us-east-1, us-west-2, and eu-west-1. Your deployment must target one of these regions.

Clone the repository

mail-catcher is designed as a standalone repo. Fork or clone it into your organization:

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

Install dependencies

bun install

This installs all workspace packages including the API, ingest handler, infrastructure, and E2E tests.

Project structure

mail-catcher/
├── sst.config.ts                  # SST app configuration
├── scripts/provision.ts           # API key management CLI
├── apps/
│   ├── api/src/                   # REST API (Hono on Lambda)
│   │   ├── index.ts               # App factory and route setup
│   │   ├── routes/v1/emails.ts    # Email endpoints
│   │   ├── middleware/auth.ts     # Bearer token authentication
│   │   └── schemas.ts            # Zod validation schemas
│   └── ingest/src/                # Email parser (S3 event handler)
│       ├── ingest.ts              # S3 event → parse → DynamoDB
│       └── email-parser.ts        # RFC 5322 header extraction
├── packages/
│   ├── core/src/                  # Shared DynamoDB operations
│   │   └── dynamo.ts              # Read/write/delete operations
│   └── infra/src/                 # AWS infrastructure definitions
│       ├── index.ts               # S3, DynamoDB, Lambda, Router
│       └── ses-inbound.ts         # SES receipt rules and DNS
├── e2e/                           # End-to-end tests
└── www/                           # Documentation site (you're reading it)

Monorepo layout

mail-catcher uses Bun workspaces. The key packages are:

Package	Purpose
`apps/api`	Hono REST API running on Lambda
`apps/ingest`	S3 event handler that parses emails into DynamoDB
`packages/core`	Shared DynamoDB query/write operations
`packages/infra`	SST/Pulumi infrastructure definitions
`e2e`	End-to-end test suite
`www`	This documentation site

Development mode

Start SST in dev mode for live Lambda reloading:

bun run dev

This provisions resources in your AWS account and creates a live development environment where Lambda changes are hot-reloaded.

Running tests

bun run test

Next steps

Configuration: environment variables and SST config
Deployment: deploy to dev and production