{"id":44716214,"url":"https://github.com/kdybicz/dispose-me","last_synced_at":"2026-02-17T23:13:37.522Z","repository":{"id":38453301,"uuid":"312812559","full_name":"kdybicz/dispose-me","owner":"kdybicz","description":"Dispose Me is a simple AWS-hosted disposable email service.","archived":false,"fork":false,"pushed_at":"2026-02-13T22:20:13.000Z","size":6503,"stargazers_count":5,"open_issues_count":8,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-13T23:57:52.767Z","etag":null,"topics":["aws","aws-cdk","cdk","devops","disposable","disposable-email","ejs","emails","expressjs","serverless","test-automation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kdybicz.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"kdybicz"}},"created_at":"2020-11-14T12:28:14.000Z","updated_at":"2026-02-13T22:20:15.000Z","dependencies_parsed_at":"2025-05-18T13:29:47.012Z","dependency_job_id":"d6598109-50e6-4119-bdc7-4f7b1d2b972d","html_url":"https://github.com/kdybicz/dispose-me","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/kdybicz/dispose-me","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdybicz%2Fdispose-me","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdybicz%2Fdispose-me/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdybicz%2Fdispose-me/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdybicz%2Fdispose-me/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kdybicz","download_url":"https://codeload.github.com/kdybicz/dispose-me/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kdybicz%2Fdispose-me/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29480863,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T11:35:25.641Z","status":"ssl_error","status_checked_at":"2026-02-15T11:34:57.128Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","aws-cdk","cdk","devops","disposable","disposable-email","ejs","emails","expressjs","serverless","test-automation"],"created_at":"2026-02-15T14:03:03.984Z","updated_at":"2026-02-15T14:03:04.822Z","avatar_url":"https://github.com/kdybicz.png","language":"TypeScript","readme":"[![CodeQL Advanced](https://github.com/kdybicz/dispose-me/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/kdybicz/dispose-me/actions/workflows/codeql-analysis.yml)\n[![Node.js CI](https://github.com/kdybicz/dispose-me/actions/workflows/tests.yml/badge.svg)](https://github.com/kdybicz/dispose-me/actions/workflows/tests.yml)\n\n# Dispose Me\n\nDispose Me is a simple AWS-hosted disposable email service.\n\n\n## TL;DR\n\n1. Own a Route53-manageable domain with in a Region supporting SES incoming\n   emails.\n2. Create a project-dedicated AWS user for project deployment (optional).\n3. Download the code, create and fill out `.env` file - based on\n   `.env.example`.\n4. Run `pnpm deploy` to install dependencies, run tests, and deploy the stack.\n5. Have fun!\n\n\n## Tech Stack\n\n### Frameworks\n\n- [Node.js](https://github.com/nodejs/node)\n- [express.js](https://github.com/expressjs/express)\n- [EJS](https://github.com/mde/ejs)\n- [AWS CDK](https://aws.amazon.com/cdk/)\n- [AWS SAM](https://aws.amazon.com/serverless/sam/)\n- [webpack](https://github.com/webpack/webpack)\n\n### AWS Services\n\n- Api Gateway\n- CloudFormation\n- DynamoDB\n- Lambda with custom Authorizer\n- Route53\n- Simple Email Service\n- Simple Storage Service\n\n\n## API Documentation\n\nYou can find the full OpenAPI (Swagger) schema for the Dispose Me API in the repository:\n\n- **Schema file:** [`docs/schema.yaml`](docs/schema.yaml)\n\nYou can also view and explore the API interactively using the online Swagger UI:\n\n- **Online schema viewer:**  \n  [https://petstore.swagger.io/?url=https://raw.githubusercontent.com/kdybicz/dispose-me/refs/heads/master/docs/schema.yaml](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/kdybicz/dispose-me/refs/heads/master/docs/schema.yaml)\n\n\n## Setup process\n\n### Environment\n\nFirst, please make sure you have [Node.js installed](https://nodejs.org/en/download/package-manager/) in version v22.x or above.\n\nYou can easily verify the installed Node.js version by running:\n\n```\n$ node -v\nv22.16.0\n```\n\nAdditionally, you will need the latest version of [AWS CDK](https://aws.amazon.com/cdk/)\nand [AWS SAM](https://aws.amazon.com/serverless/sam/).\n\nYou can verify if they are installed by running:\n\n```\n$ cdk --version\n2.158.0 (build 4b8714d)\n\n$ sam --version\nSAM CLI, version 1.122.0\n```\n\n### Getting the project\n\nDownload the project source code using `git`:\n\n```\n$ git clone https://github.com/kdybicz/dispose-me.git\n```\n\nOr download as a `zip` file from https://github.com/kdybicz/dispose-me/archive/\nmaster.zip and unpack it into a folder of your choosing.\n\nNext, run `pnpm install` to install all required dependencies:\n\n```\n$ cd dispose-me\n$ pnpm install\n```\n\nOptionally, run the tests to ensure the code is running properly:\n\n```\n$ pnpm test\n```\n\n### AWS user\n\n**Note:** Next steps assume you already have an AWS account and you're logged\ninto the AWS Console!\n\nIt's a good practice to use a dedicated user for each AWS project. This makes\nit easier to control which projects use what permissions.\n\nCreate a new user with Programmatic access only by going to:\n\nhttps://console.aws.amazon.com/iam/home?#/users$new?step=details\n\nSelect _Attach policies directly_ in the _Set permissions_ section, click\n_Create policy_, change the editor to _JSON_, and paste the policy below. Then\nproceed to finalize the user creation.\n\n```\n{\n\t\"Version\": \"2012-10-17\",\n\t\"Statement\": [\n\t\t{\n\t\t\t\"Effect\": \"Allow\",\n\t\t\t\"Action\": [\n\t\t\t\t\"cloudformation:*\",\n\t\t\t\t\"ecr:*\",\n\t\t\t\t\"ssm:*\",\n\t\t\t\t\"s3:*\",\n\t\t\t\t\"iam:*\",\n\t\t\t\t\"route53:*\"\n\t\t\t],\n\t\t\t\"Resource\": \"*\"\n\t\t}\n\t]\n}\n```\n\n**Note:** At the last step, you will receive user credentials. Be sure to copy\nthem and use them to set up AWS CLI access to your account. Follow the guide\nhere: https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-user.html\n\n### Setup a Domain\n\nTo use Simple Email Service, you need to associate a domain with your AWS\naccount. This means using Route53 to:\n\n- Buy a domain: https://console.aws.amazon.com/route53/home#DomainRegistration\n- Or transfer an existing domain: https://console.aws.amazon.com/route53/home#DomainTransfer\n\n**Note:** Domains are not free. Choose one that's affordable to buy and\nmaintain, like `.de` or `.uk`. For domain prices, refer to\nhttps://aws.amazon.com/route53/pricing/\n\n### Choose the Region\n\nSelect a region that supports receiving emails via SES:\nhttps://docs.aws.amazon.com/ses/latest/DeveloperGuide/regions.html#region-receive-email\n\n\n**Note:** This region will be used in the next steps and also during code\ndeployment. This will be referred to as the **Region** in the documentation.\n\n### Deploy\n\nRefer to the `.env.example` file and create your own `.env` file. Use the\ncomments inside for guidance. Once done, deploy the code to AWS by running:\n\n```\n$ pnpm deploy\n```\n\nAPI access key can be found in the `Terminal` output under the\n`DisposeMeStack.ApiKeyValue` key:\n```\nOutputs:\nDisposeMeStack.ApiGatewayEndpoint5BB8GD2A = https://abcdefg123.execute-api.eu-west-1.amazonaws.com/production/\nDisposeMeStack.ApiKeyValue = n78CXFciT68XyyfEb1depypckhUSg6capqvMNJGW\n````\nor you can go to the _API Gateway_ section of the AWS Console\nand check _API keys_.\n\n**Note:** If you encounter any issues, raise an Issue with steps taken and\nerror messages.\n\n### Time for tests\n\nGo to: https://DOMAIN_NAME/?x-api-key=ACCESS_TOKEN\n\n**Note:** You can also send the `ACCESS_TOKEN` in the `x-api-key` request\nHeader.\n\n\n## Opening to public\n\nSome of you may want to open the service to the public. While this seems like\na great idea, be aware of the risks involved. Ensure you know what you're\ndoing! I'm not a security expert, but I can share suggestions left by @shokinn.\n\n### The Suggestion\n\nCertain email addresses have more power than others, like how an administrator\naccount on a computer is more powerful than a regular user. It's crucial not\nto open those addresses to the public, as someone could impersonate you,\npotentially leading to missed warnings or losing the domain.\n\nHere is a list of such inbox names, also restricted in\n[Google Services](https://support.google.com/a/answer/6093413?hl=en). This list\nis based on [RFC 2142](https://www.ietf.org/rfc/rfc2142.txt) with some\nadditions.\n\n### Setting it up\n\nTo open the service to the public, copy and uncomment two lines of code from\nthe `.env.example`:\n\n```\nPRIVATE_ACCESS=false\n\nINBOX_BLACKLIST=hostmaster,postmaster,webmaster,admin,administrator,abuse,root,ssl-admin,majordomo\n```\n\n**Note:** Do not ignore the importance of `INBOX_BLACKLIST`.\n\nRedeploy the service, and you're done.\n\n### Beyond the bare minimum\n\nYou can further ensure that any emails sent to these powerful email addresses\nare never processed by Lambda. This prevents anyone from bypassing the\nblacklist and reading emails from these inboxes.\n\nThe current setup automatically creates a rule that stops processing any\nemails matching the `INBOX_BLACKLIST`. By default, the list will look like:\n\n- hostmaster@`DOMAIN_NAME`\n- postmaster@`DOMAIN_NAME`\n- webmaster@`DOMAIN_NAME`\n- admin@`DOMAIN_NAME`\n- administrator@`DOMAIN_NAME`\n- abuse@`DOMAIN_NAME`\n- root@`DOMAIN_NAME`\n- ssl-admin@`DOMAIN_NAME`\n- majordomo@`DOMAIN_NAME`\n\nHere you can find more details:\nhttps://docs.aws.amazon.com/ses/latest/DeveloperGuide/receiving-email-action-stop.html\n\n\n## Costs simulation\n\n\u003e This is an example of potential costs. It's an estimate, not verified by\n\u003e long-term usage, and may vary depending on your case. **BE WARNED**.\n\n- `.de` domain: $9.00 per year\n- Hosted Zones and Records: $0.50 per hosted zone / month\n- Public SSL Certificate: Free via AWS Certificate Manager\n- Simple Email Service:\n  - Free Tier: $0 for the first 1,000 emails you receive, $0.10 per additional\n    1,000 emails.\n  - Later: $0.09 per 1,000 incoming email chunks (see\n\t  [Pricing details](https://aws.amazon.com/ses/pricing/#Pricing_details)).\n- Simple Storage Service:\n  - Storage: $0.023 per GB for the first 50 TB / Month.\n  - Requests \u0026 data retrievals:\n    - PUT, COPY, POST, LIST requests (per 1,000): $0.005\n    - GET, SELECT, and others (per 1,000): $0.0004\n  - Data Transfer: 1 GB / Month - $0.00 per GB\n- Lambda 512MB: $0.0000008333 per 100ms\n\n**Example for Small Scale Usage on Free Tier**:\n\n- Domain + Hosted Zone: $9.00/year + $0.25 * 12 months = $12.00/year\n- Incoming emails (1,000/month): (12 - 1) * $0.10 = $1.10\n- Average Lambda processing time (300ms): 12,000 emails * (300 ms / 100 ms) *\n  $0.0000008333 = $0.03\n- Average 300ms API Lambda time per request (5x more requests than emails):\n  $0.03 * 5 = $0.15\n- S3 operations (assuming plain text/html emails, 84,000 requests): 84,000 /\n  1,000 * $0.005 = $0.42\n\n**Total**: ~$15.00 + TAX per year\n","funding_links":["https://github.com/sponsors/kdybicz"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdybicz%2Fdispose-me","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkdybicz%2Fdispose-me","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkdybicz%2Fdispose-me/lists"}