Maildummy

SES-based email capture for automated testing. Intercepts emails sent to a maildummy.* subdomain, stores them in S3, and lets your E2E tests retrieve magic links or other content.

How it works

1. An MX record routes mail for maildummy.example.com to AWS SES
2. An SES receipt rule stores each message as a raw MIME file in S3 under raw/
3. Helper scripts (Node.js or Python) list the bucket, parse the MIME, and extract URLs

Infrastructure options

Maildummy ships two equivalent ways to provision the AWS resources:

Option	Location	DNS support
Terraform module	terraform/modules/ses_maildummy	Cloudflare or Route53
CDK construct	cdk/ (@de-otio/maildummy-cdk)	Route53 (or bring your own)

Both create the same set of resources: SES domain identity, S3 bucket, SNS topic, SES receipt rule, and the required IAM policies.

Documentation

• Terraform module reference
• CDK construct reference
• Deployment guide - initial setup, DKIM, troubleshooting
• E2E testing guide - wiring maildummy into your test suite
• Helper scripts - retrieving magic links from S3

Quick start (Terraform)

module "maildummy" {
  source = "github.com/your-org/maildummy//terraform/modules/ses_maildummy"

  maildummy_domain      = "maildummy.example.com"
  maildummy_subdomain   = "maildummy"
  dns_provider          = "route53"
  route53_zone_id       = "Z1234567890ABC"
  aws_region            = "eu-central-1"
  s3_bucket_name        = "my-project-maildummy"
  sns_topic_name        = "my-project-maildummy-notifications"
  receipt_rule_set_name = "my-existing-ruleset"
  receipt_rule_name     = "my-project-maildummy-rule"
}

Quick start (CDK)

import { Maildummy } from "@de-otio/maildummy-cdk";

new Maildummy(stack, "Maildummy", {
  maildummyDomain: "maildummy.example.com",
  receiptRuleSetName: "my-existing-ruleset",
  hostedZone: myZone,
});

License

MIT