{"id":51153124,"url":"https://github.com/pexni/smails","last_synced_at":"2026-06-26T08:01:45.717Z","repository":{"id":367139051,"uuid":"1279301508","full_name":"pexni/smails","owner":"pexni","description":"Agent-native disposable email — Cloudflare Workers + Durable Objects, with CLI \u0026 MCP. https://smails.dev","archived":false,"fork":false,"pushed_at":"2026-06-24T18:43:54.000Z","size":274,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T19:11:09.828Z","etag":null,"topics":["ai-agents","cli","cloudflare-workers","disposable-email","durable-objects","email-api","mcp","model-context-protocol","temporary-email","throwaway-email"],"latest_commit_sha":null,"homepage":"https://smails.dev","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/pexni.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-06-24T14:59:55.000Z","updated_at":"2026-06-24T18:43:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pexni/smails","commit_stats":null,"previous_names":["pexni/smails"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/pexni/smails","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pexni%2Fsmails","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pexni%2Fsmails/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pexni%2Fsmails/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pexni%2Fsmails/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pexni","download_url":"https://codeload.github.com/pexni/smails/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pexni%2Fsmails/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34808043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","cli","cloudflare-workers","disposable-email","durable-objects","email-api","mcp","model-context-protocol","temporary-email","throwaway-email"],"created_at":"2026-06-26T08:01:45.062Z","updated_at":"2026-06-26T08:01:45.708Z","avatar_url":"https://github.com/pexni.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# smails\n\n[![npm](https://img.shields.io/npm/v/@smails/cli?color=000\u0026label=%40smails%2Fcli)](https://www.npmjs.com/package/@smails/cli)\n[![smails.dev](https://img.shields.io/badge/try-smails.dev-000)](https://smails.dev)\n[![MIT](https://img.shields.io/badge/license-MIT-000)](./LICENSE)\n\n**Disposable email for humans and AI agents.** An instant, anonymous throwaway inbox for sign-ups, one-time codes, and confirmations — with a REST API, a CLI, and an **MCP server**, so your AI agent can receive verification emails too. No signup, no password.\n\n→ **[smails.dev](https://smails.dev)** · `npx @smails/cli create`\n\n\u003e Give your agent its own inbox: plug the MCP server into Claude, Cursor, or any MCP client and it can create a mailbox and read incoming mail (verification codes, magic links) on its own.\n\n## Features\n\n- **Instant inbox** — open the site and you have an address, zero clicks\n- **Real-time** — new mail arrives over WebSocket, no polling\n- **Built for agents** — REST API, CLI, and an MCP server share the same mailbox\n- **Multi-domain** — pick from configurable receiving domains\n- **Self-cleaning** — mailboxes auto-expire after 7 days of inactivity\n- **Serverless** — Cloudflare Workers + Durable Objects (one DO per mailbox, SQLite storage)\n\n## Quick start\n\n### Web\n\nVisit **[smails.dev](https://smails.dev)** — an inbox is created for you on first load.\n\n### CLI\n\n```bash\nnpx @smails/cli create      # create a mailbox (token saved to ~/.smails)\nnpx @smails/cli inbox       # list messages\nnpx @smails/cli read \u003cid\u003e   # read a message (id prefix is enough)\nnpx @smails/cli whoami      # show the current address\nnpx @smails/cli create --new  # replace with a fresh mailbox\n```\n\n### MCP (for AI agents)\n\nAdd the server to any MCP client (e.g. Claude Desktop, `~/.claude/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"smails\": { \"command\": \"npx\", \"args\": [\"@smails/cli\", \"mcp\"] }\n  }\n}\n```\n\nTools: `create_mailbox`, `list_messages`, `read_message`, `delete_message`, `get_address`.\n\n### REST API\n\n```bash\n# create a mailbox\ncurl -X POST https://smails.dev/api/mailbox\n# → { \"address\": \"...\", \"token\": \"...\" }\n\n# list messages with the returned token\ncurl https://smails.dev/api/mailbox/messages \\\n  -H \"Authorization: Bearer \u003ctoken\u003e\"\n```\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/api/mailbox` | Create a mailbox → `{ address, token }` |\n| `GET` | `/api/mailbox/messages` | List messages |\n| `GET` | `/api/mailbox/messages/:id` | Read a message (full parsed body) |\n| `DELETE` | `/api/mailbox/messages/:id` | Delete a message |\n| `WS` | `/api/mailbox/connect?token=` | Stream new-mail notifications |\n\nAuthenticate every request (except create) with `Authorization: Bearer \u003ctoken\u003e`.\n\n## How it works\n\n```\nInbound mail ──▶ Cloudflare Email Routing (catch-all)\n                          │\n                          ▼\n                  Worker  email() handler ──┐\n                                            ▼\n   Web / CLI / MCP ──REST + WS──▶  Durable Object  (one per mailbox)\n                                   ├─ SQLite (messages)\n                                   ├─ token auth\n                                   └─ 7-day alarm → cleanup\n```\n\n- Each mailbox is a single **Durable Object**, addressed by its name; messages live in the DO's SQLite.\n- The token is `{address}.{secret}`; the Worker routes by address, the DO verifies the full token.\n- A 7-day alarm wipes inactive mailboxes; any activity renews it.\n\n## Project structure\n\n```\nfrontend/   React Router SPA (prerendered) — Tailwind v4 + shadcn\nworker/     Cloudflare Worker + Durable Objects — Hono routing, postal-mime parsing\ncli/        npm package — CLI + MCP server (@smails/cli)\n```\n\n## Development\n\nEach package is independent (pnpm). Install per package.\n\n```bash\n# frontend\ncd frontend \u0026\u0026 pnpm install \u0026\u0026 pnpm dev\n\n# worker (API + Durable Objects)\ncd worker \u0026\u0026 pnpm install \u0026\u0026 pnpm dev\n\n# cli / mcp\ncd cli \u0026\u0026 pnpm install \u0026\u0026 pnpm build\nSMAILS_API_URL=http://localhost:8787 node dist/index.js create\n```\n\n## Deployment\n\nThe frontend builds to static assets that the Worker serves, so it's a single deploy:\n\n```bash\ncd frontend \u0026\u0026 pnpm build      # → build/client\ncd ../worker \u0026\u0026 pnpm run deploy   # wrangler deploy — serves assets + API + DOs\n```\n\nReceiving mail uses Cloudflare Email Routing (catch-all → the Worker's `email` handler). Configure receiving domains via the `DOMAINS` var and the route in `worker/wrangler.jsonc`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpexni%2Fsmails","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpexni%2Fsmails","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpexni%2Fsmails/lists"}