{"id":21857768,"url":"https://github.com/mv-consulting/awscdk-rootmail","last_synced_at":"2026-03-14T10:02:04.144Z","repository":{"id":202637672,"uuid":"669239407","full_name":"MV-Consulting/awscdk-rootmail","owner":"MV-Consulting","description":"An opinionated way to secure your AWS root email boxes","archived":false,"fork":false,"pushed_at":"2024-05-23T00:34:32.000Z","size":11591,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-23T01:35:42.073Z","etag":null,"topics":["aws","cdk","cdk-construct","mail","opinionated","security"],"latest_commit_sha":null,"homepage":"https://manuel-vogel.de/post/2023-10-18-migrate-rootmail-to-cdk/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MV-Consulting.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-21T17:31:25.000Z","updated_at":"2024-08-27T02:00:35.712Z","dependencies_parsed_at":null,"dependency_job_id":"7d7aedf0-967b-4aaf-b40a-61e8a9ad309c","html_url":"https://github.com/MV-Consulting/awscdk-rootmail","commit_stats":null,"previous_names":["mv-consulting/awscdk-rootmail","mavogel/awscdk-rootmail"],"tags_count":293,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MV-Consulting%2Fawscdk-rootmail","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MV-Consulting%2Fawscdk-rootmail/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MV-Consulting%2Fawscdk-rootmail/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MV-Consulting%2Fawscdk-rootmail/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MV-Consulting","download_url":"https://codeload.github.com/MV-Consulting/awscdk-rootmail/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244855198,"owners_count":20521605,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cdk","cdk-construct","mail","opinionated","security"],"created_at":"2024-11-28T02:31:31.261Z","updated_at":"2026-03-14T10:02:04.031Z","avatar_url":"https://github.com/MV-Consulting.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Source](https://img.shields.io/github/stars/MV-Consulting/awscdk-rootmail?logo=github\u0026label=GitHub%20Stars)\n[![Build Status](https://github.com/MV-Consulting/awscdk-rootmail/actions/workflows/build.yml/badge.svg)](https://github.com/MV-Consulting/awscdk-rootmail/actions/workflows/build.yml)\n[![ESLint Code Formatting](https://img.shields.io/badge/code_style-eslint-brightgreen.svg)](https://eslint.org)\n[![Latest release](https://img.shields.io/github/release/MV-Consulting/awscdk-rootmail.svg)](https://github.com/MV-Consulting/awscdk-rootmail/releases)\n![GitHub](https://img.shields.io/github/license/MV-Consulting/awscdk-rootmail)\n[![npm](https://img.shields.io/npm/dt/@mavogel/awscdk-rootmail?label=npm\u0026color=orange)](https://www.npmjs.com/package/@mavogel/awscdk-rootmail)\n[![typescript](https://img.shields.io/badge/jsii-typescript-blueviolet.svg)](https://www.npmjs.com/package/@mavogel/cdk-vscode-server)\n\n# awscdk-rootmail\n\nA single email box for all your root user emails in all AWS accounts of the organization. \n- The cdk implementation and **adaption** of the [superwerker](https://superwerker.cloud/) rootmail feature. \n- See [here](docs/adrs/rootmail.md) for a detailed Architectural Decision Record ([ADR](https://adr.github.io/))\n\n## TL;DR ⚡\nEach AWS account needs one unique email address (the so-called \"AWS account root user email address\").\n\nAccess to these email addresses must be adequately secured since they provide privileged access to AWS accounts, such as account deletion procedures.\n\nThis is why you only need 1 mailing list for the AWS Management (formerly *root*) account, \nwe recommend the following pattern `aws-roots+\u003cuuid\u003e@mycompany.test` \n\n\u003e [!NOTE]\n\u003e Maximum **64** characters are allowed for the whole address. \n\nAnd as you own the domain `mycompany.test` you can add a subdomain, e.g. `aws`, for which all EMails will then be received with this solution within this particular AWS Management account.\n\nFeel free to take a look at the design \n![rootmail-solution-diagram-v1](docs/img/awscdk-rootmail-v1-min.png)\n\n## Usage ✨\n\nInstall the dependencies:\n```sh\nbrew install aws-cli node@18 esbuild\n```\n\nYou can chose via embedding the construct in your cdk-app or use is directly via Cloudformation.\n### cdk 🤖\n1. To start a new project we recommend using [projen](https://projen.io/).\n   1. Create a new projen project\n   ```sh\n   npx projen new awscdk-app-ts\n   ```\n   2. Add `@mavogel/awscdk-rootmail` as a dependency to your project in the `.projenrc.ts` file\n   3. Run `yarn run projen` to install it\n2. In you `main.ts` file add the following code\n```ts\nimport { Rootmail } from '@mavogel/awscdk-rootmail';\nimport {\n  App,\n  Stack,\n  StackProps,\n  aws_route53 as r53,\n} from 'aws-cdk-lib';\nimport { Construct } from 'constructs';\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps = {}) {\n    super(scope, id, props);\n\n    const domain = 'mycompany.com' // registered via Route53 in the SAME account\n\n    const hostedZone = r53.HostedZone.fromLookup(this, 'rootmail-parent-hosted-zone', {\n      domainName: domain,\n    });\n\n    new Rootmail(this, 'rootmail', {\n      // 1. a domain you own, registered via Route53 in the SAME account\n      domain: domain,\n      // 2. so the subdomain will be aws.mycompany.test and\n      subdomain: 'aws',\n      // 3. wired / delegated automatically to\n      wireDNSToHostedZoneID: hostedZone.hostedZoneId,\n    });\n  }\n}\n```\n2. run on your commandline\n```sh\nyarn run deploy\n```\n1. No need to do anything, the NS records are **automatically** propagated as the parent Hosted Zone is in the same account!\n2. The `hosted-zone-dkim-propagation-provider.is-complete-handler` Lambda function checks every 10 seconds if the DNS for the subdomain is propagated. Details are in the Cloudwatch log group.\n\n\u003e [!TIP]\n\u003e Take a look at the solution design [here](docs/adrs/solution-design-domain-same-aws-account.md) for more details.\n\n### cdk with your own receiver function 🏗️\nYou might also want to pass in you own function on what to do when an EMail is received\n\n\u003e [!TIP]\n\u003e You can add any custom code as receiver function you want.\n\n\u003cdetails\u003e\n  \u003csummary\u003e... click here for the details\u003c/summary\u003e\n\nfile `functions/custom-ses-receive-function.ts` which gets the 2 environment variables populated\n- `EMAIL_BUCKET`\n- `EMAIL_BUCKET_ARN`\n\nas well as `s3:GetObject` on the `RootMail/*` objects in the created Rootmail `S3` bucket. \n\n```ts\nimport { S3 } from '@aws-sdk/client-s3';\nimport { ParsedMail, simpleParser } from 'mailparser';\n// populated by default\nconst emailBucket = process.env.EMAIL_BUCKET;\nconst emailBucketArn = process.env.EMAIL_BUCKET_ARN;\nconst s3 = new S3();\n\n// SESEventRecordsToLambda\n// from https://docs.aws.amazon.com/ses/latest/dg/receiving-email-action-lambda-event.html\nexport const handler = async (event: SESEventRecordsToLambda) =\u003e {\n    for (const record of event.Records) {\n        \n        const id = record.ses.mail.messageId;\n        const key = `RootMail/${id}`;\n        const response = await s3.getObject({ Bucket: emailBucket as string, Key: key });\n        \n        const msg: ParsedMail = await simpleParser(response.Body as unknown as Buffer);\n        \n        let title = msg.subject;\n        console.log(`Title: ${title} from emailBucketArn: ${emailBucketArn}`);\n        // use the content of the email body \n        const body = msg.html;\n        // add your custom code here ...\n\n        // dummy example: list s3 buckets\n        const buckets = await s3.listBuckets({});\n        if (!buckets.Buckets) {\n            console.log('No buckets found');\n            return;\n        }\n        console.log('Buckets:');\n        for (const bucket of buckets.Buckets || []) {\n            console.log(bucket.Name);\n        }\n    }\n\n};\n```\nand you create a separate `NodejsFunction` as follows with the additionally needed IAM permissions:\n```ts\nconst customSesReceiveFunction = new NodejsFunction(stackUnderTest, 'custom-ses-receive-function', {\n  functionName: PhysicalName.GENERATE_IF_NEEDED,\n  entry: path.join(__dirname, 'functions', 'custom-ses-receive-function.ts'),\n  runtime: lambda.Runtime.NODEJS_18_X,\n  logRetention: 1,\n  timeout: Duration.seconds(30),\n});\n\n// Note: any additional permissions you need to add to the function yourself!\ncustomSesReceiveFunction.addToRolePolicy(new iam.PolicyStatement({\n  actions: [\n    's3:List*',\n  ],\n  resources: ['*'],\n}))\n```\nand then pass it into the `Rootmail` Stack\n```ts\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps = {}) {\n    super(scope, id, props);\n\n    const domain = 'mycompany.test'\n    const hostedZone = r53.HostedZone.fromLookup(this, 'rootmail-parent-hosted-zone', {\n      domainName: domain,\n    });\n\n    const rootmail = new Rootmail(this, 'rootmail-stack', {\n      domain: domain;\n      autowireDNSParentHostedZoneID: hostedZone.hostedZoneId,\n      env: {\n        region: 'eu-west-1',\n      },\n      customSesReceiveFunction: customSesReceiveFunction, // \u003c- pass it in here\n    }); \n  }\n}\n```\n\n\n\u003e [!TIP]\n\u003e Take a look at the solution design for external DNS [here](docs/adrs/solution-design-external-dns-provider.md) for more details.\n\n\u003c/details\u003e\n\n### Cloudformation 📦\nor use it directly a Cloudformation template `yaml` from the URL [here](https://mvc-prod-releases.s3.eu-central-1.amazonaws.com/rootmail/v0.0.258/awscdk-rootmail.template.yaml).\n\n\n\u003cdetails\u003e\n  \u003csummary\u003e... click here for the details\u003c/summary\u003e\n\nand fill out the parameters\n![cloudformation-template](docs/img/cloudformation-tpl-min.png)\n\n\u003c/details\u003e\n\n\n## Known issues\n- [jsii/2071](https://github.com/aws/jsii/issues/2071): so adding  `compilerOptions.\"esModuleInterop\": true,` in `tsconfig.json` is not possible. See aws-cdk usage with[typescript](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/#Usage_with_TypeScript). So we needed to change import from `import AWS from 'aws-sdk';` -\u003e `import * as AWS from 'aws-sdk';` to be able to compile.\n\n## Related projects / questions\n- [aws-account-factory-email](https://github.com/aws-samples/aws-account-factory-email): a similar approach with SES, however you need to manually configure it upfront and also it about delivering root mails for a specific account to a specific mailing list and mainly decouples the real email address from the one of the AWS account. The main difference is that we do not *hide* or decouple the email address, but more make those as unique and unguessable/bruteforable as possible (with `uuids`).\n- The question `Is it best practise to use a shared mailbox as AWS root user address?` from [stackoverflow](https://stackoverflow.com/questions/76739635/is-it-best-practise-to-use-a-shared-mailbox-as-aws-root-user-address): yes of course you can also use `root+alias-1@mycompany.com` and `root+alias-2@mycompany.com` etc. for your\nroot EMail boxes.\n\n## 🚀 Unlock the Full Potential of Your AWS Cloud Infrastructure  \n\nHi, I’m Manuel, an AWS expert passionate about empowering businesses with **scalable, resilient, and cost-optimized cloud solutions**. With **MV Consulting**, I specialize in crafting **tailored AWS architectures** and **DevOps-driven workflows** that not only meet your current needs but grow with you.  \n\n---\n\n### 🌟 Why Work With Me?  \n\n✔️ **Tailored AWS Solutions:** Every business is unique, so I design custom solutions that fit your goals and challenges.  \n✔️ **Well-Architected Designs:** From scalability to security, my solutions align with AWS Well-Architected Framework.  \n✔️ **Cloud-Native Focus:** I specialize in modern, cloud-native systems that embrace the full potential of AWS.  \n✔️ **Business-Driven Tech:** Technology should serve your business, not the other way around.  \n\n---\n\n### 🛠 What I Bring to the Table  \n\n🔑 **12x AWS Certifications**  \nI’m **AWS Certified Solutions Architect and DevOps – Professional** and hold numerous additional certifications, so you can trust I’ll bring industry best practices to your projects. Feel free to explose by [badges](https://www.credly.com/users/manuel-vogel)\n\n⚙️ **Infrastructure as Code (IaC)**  \nWith deep expertise in **AWS CDK** and **Terraform**, I ensure your infrastructure is automated, maintainable, and scalable.  \n\n📦 **DevOps Expertise**  \nFrom CI/CD pipelines with **GitHub Actions** and **GitLab CI** to container orchestration **Kubernetes** and others, I deliver workflows that are smooth and efficient.  \n\n🌐 **Hands-On Experience**  \nWith over **7 years of AWS experience** and a decade in the tech world, I’ve delivered solutions for companies large and small. My open-source contributions showcase my commitment to transparency and innovation. Feel free to explore my [GitHub profile](https://github.com/mavogel)\n\n---\n\n### 💼 Let’s Build Something Great Together  \n\nI know that choosing the right partner is critical to your success. When you work with me, you’re not just contracting an engineer – you’re gaining a trusted advisor and hands-on expert who cares about your business as much as you do.  \n\n✔️ **Direct Collaboration**: No middlemen or red tape – you work with me directly.  \n✔️ **Transparent Process**: Expect open communication, clear timelines, and visible results.  \n✔️ **Real Value**: My solutions focus on delivering measurable impact for your business.  \n\n\n\u003ca href=\"https://tinyurl.com/mvc-15min\"\u003e\u003cimg alt=\"Schedule your call\" src=\"https://img.shields.io/badge/schedule%20your%20call-success.svg?style=for-the-badge\"/\u003e\u003c/a\u003e  \n\n---\n\n## 🙌 Acknowledgements\n\nBig shoutout to the amazing team behind [Projen](https://github.com/projen/projen)!  \nTheir groundbreaking work simplifies cloud infrastructure projects and inspires us every day. 💡\n\n## Author\n\n[Manuel Vogel](https://manuel-vogel.de/about/)\n\n[![](https://img.shields.io/badge/LinkedIn-0077B5?style=for-the-badge\u0026logo=linkedin\u0026logoColor=white)](https://www.linkedin.com/in/manuel-vogel)\n[![](https://img.shields.io/badge/GitHub-2b3137?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/mavogel)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmv-consulting%2Fawscdk-rootmail","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmv-consulting%2Fawscdk-rootmail","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmv-consulting%2Fawscdk-rootmail/lists"}