{"id":47979936,"url":"https://github.com/rodavel-labs/mail-catcher","last_synced_at":"2026-04-04T11:03:47.306Z","repository":{"id":344073545,"uuid":"1180343202","full_name":"rodavel-labs/mail-catcher","owner":"rodavel-labs","description":"📨 Serverless inbound email API. Receive emails via AWS SES, query them via REST. Built for E2E testing and email ingestion pipelines.","archived":false,"fork":false,"pushed_at":"2026-03-27T20:33:05.000Z","size":205,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T02:54:22.427Z","etag":null,"topics":["aws","aws-ses","dynamodb","e2e-testing","email","hono","lambda","s3","serverless","sst","typescript"],"latest_commit_sha":null,"homepage":"https://rodavel.com/docs/mail-catcher","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/rodavel-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T00:17:38.000Z","updated_at":"2026-03-27T20:31:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"68b3eabb-6257-4770-a7ad-540203c58834","html_url":"https://github.com/rodavel-labs/mail-catcher","commit_stats":null,"previous_names":["rodpadev/ses-inbox","rodavel-labs/ses-inbox","rodavel-labs/mail-catcher"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/rodavel-labs/mail-catcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodavel-labs%2Fmail-catcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodavel-labs%2Fmail-catcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodavel-labs%2Fmail-catcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodavel-labs%2Fmail-catcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rodavel-labs","download_url":"https://codeload.github.com/rodavel-labs/mail-catcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rodavel-labs%2Fmail-catcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31397056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: 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-ses","dynamodb","e2e-testing","email","hono","lambda","s3","serverless","sst","typescript"],"created_at":"2026-04-04T11:03:13.168Z","updated_at":"2026-04-04T11:03:47.282Z","avatar_url":"https://github.com/rodavel-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mail-catcher\n\n[![CI](https://github.com/rodavel-labs/mail-catcher/actions/workflows/ci.yml/badge.svg)](https://github.com/rodavel-labs/mail-catcher/actions/workflows/ci.yml)\n\nServerless inbound email API. Receives emails via AWS SES, stores raw `.eml` files in S3, indexes metadata in DynamoDB, and exposes a REST API to query and retrieve them.\n\nBuilt for E2E testing workflows and email ingestion pipelines.\n\n## Architecture\n\n```mermaid\nflowchart LR\n    Sender[\"Email Sender\"] --\u003e|SMTP| MX[\"MX Record\"]\n    MX --\u003e SES[\"AWS SES\"]\n    SES --\u003e|PutObject| S3[\"S3 Bucket\\n(raw .eml)\"]\n    S3 --\u003e|ObjectCreated| Ingest[\"Ingest Lambda\"]\n    Ingest --\u003e|PutItem| DDB[\"DynamoDB\\n(metadata)\"]\n    Client[\"API Client\"] --\u003e|GET /emails| API[\"API Lambda\\n(Hono)\"]\n    API --\u003e|Query| DDB\n    API --\u003e|Pre-signed URL| S3\n```\n\n## Quick Start\n\n```bash\ngit clone \u003cyour-repo-url\u003e mail-catcher\ncd mail-catcher\nbun install\ncp .env.example .env     # Configure AWS_REGION, SES_DOMAIN, etc.\nbun run deploy:dev       # Deploy to AWS\nbun run provision --create --name my-key  # Create an API key\n```\n\nThen query emails:\n\n```bash\ncurl -H \"Authorization: Bearer \u003ctoken\u003e\" \\\n  \"\u003capi-url\u003e/emails?inbox=test\u0026wait=true\"\n```\n\n## Documentation\n\nFull documentation is available at [rodavel.com/docs/mail-catcher](https://rodavel.com/collection/mail-catcher).\n\n## Scripts\n\n| Command | Description |\n| --- | --- |\n| `bun run deploy:dev` | Deploy to dev stage |\n| `bun run deploy:prod` | Deploy to production |\n| `bun run dev` | Start SST dev mode (live Lambda) |\n| `bun run remove:dev` | Remove dev stage |\n| `bun run provision` | Manage API keys |\n| `bun run test` | Run tests |\n| `bun run lint` | Run Biome linter |\n\n## Project Structure\n\n```text\n├── sst.config.ts                  # SST app configuration\n├── scripts/provision.ts           # API key management CLI\n├── apps/\n│   ├── api/src/                   # REST API (Hono on Lambda)\n│   │   ├── index.ts               # App factory and route setup\n│   │   ├── routes/v1/emails.ts    # Email endpoints\n│   │   ├── middleware/auth.ts     # Bearer token authentication\n│   │   └── schemas.ts            # Zod validation schemas\n│   └── ingest/src/                # Email parser (S3 event handler)\n│       ├── ingest.ts              # S3 event → parse → DynamoDB\n│       └── email-parser.ts        # RFC 5322 header extraction\n├── packages/\n│   ├── core/src/                  # Shared DynamoDB operations\n│   │   └── dynamo.ts              # Read/write/delete operations\n│   └── infra/src/                 # AWS infrastructure definitions\n│       ├── index.ts               # S3, DynamoDB, Lambda, Router\n│       └── ses-inbound.ts         # SES receipt rules and DNS\n├── e2e/                           # End-to-end tests\n```\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodavel-labs%2Fmail-catcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frodavel-labs%2Fmail-catcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frodavel-labs%2Fmail-catcher/lists"}