Configuration
Environment variables and SST configuration reference.
mail-catcher is configured through environment variables loaded from a .env file at the project root.
Setup
cp .env.example .envRequired variables
| Variable | Description | Example |
|---|---|---|
AWS_PROFILE | AWS CLI profile to use for deployment | default |
AWS_REGION | Target AWS region (must support SES inbound) | us-east-1 |
SES_DOMAIN | Domain for receiving emails | receive.yourdomain.com |
AWS_REGION
Must be one of the three regions that support SES inbound email:
us-east-1(US East, N. Virginia)us-west-2(US West, Oregon)eu-west-1(Europe, Ireland)
SES_DOMAIN
The domain (or subdomain) that will receive emails. Use a subdomain like receive.yourdomain.com rather than your root domain to avoid conflicts with existing MX records.
Optional variables
| Variable | Description | Example |
|---|---|---|
HOSTED_ZONE_ID | Route 53 hosted zone ID for automatic DNS | Z1234567890ABC |
API_DOMAIN | Custom domain for the API endpoint | api.inbox.yourdomain.com |
MAX_ATTACHMENT_SIZE | Max size per attachment in bytes (ingest) | 10485760 |
MAX_ATTACHMENTS | Max number of attachments per email (ingest) | 20 |
How they interact
HOSTED_ZONE_ID | API_DOMAIN | Behavior |
|---|---|---|
| set | set | Custom domain with automatic DNS and certificate |
| set | omitted | Default Lambda URL with automatic SES DNS records |
| omitted | set | Custom domain using a pre-provisioned ACM certificate |
| omitted | omitted | Default Lambda URL, DNS records exported as BIND zone file |
HOSTED_ZONE_ID
When set, SST automatically creates:
- MX record for SES email reception
- TXT record for SES domain verification
- ACM certificate (if
API_DOMAINis also set) - CNAME for CloudFront (if
API_DOMAINis also set)
When omitted, the deploy writes a .sst/dns-records.zone file with all the records you need to add manually.
API_DOMAIN
When set, SST creates a CloudFront distribution with your custom domain. Without HOSTED_ZONE_ID, you must pre-provision an ACM certificate for this domain. See Deployment: ACM certificate.
MAX_ATTACHMENT_SIZE
Maximum allowed size (in bytes) for a single attachment during email ingestion. Attachments exceeding this limit are skipped. When omitted, there is no size limit.
MAX_ATTACHMENTS
Maximum number of attachments to process per email. When omitted, all attachments are processed.
SST stages
SST uses stages to isolate environments. Each stage creates its own independent set of resources:
bun run deploy:dev # deploys to "dev" stage
bun run deploy:prod # deploys to "prod" stageStages share the same AWS account but all resource names are prefixed with the stage name, so there's no collision.
Data retention defaults
All data auto-expires by default. See Data Retention for the full breakdown and customization instructions.