{"_id":"@damazco/email-explorer","_rev":"2-24bbf7662bae519100a551b0590a4238","name":"@damazco/email-explorer","dist-tags":{"latest":"1.2.1"},"versions":{"1.2.0":{"name":"@damazco/email-explorer","version":"1.2.0","keywords":["cloudflare","worker","workers","serverless","cloudflare email routing","cloudflare email sending","gmail","ui","cf","typescript","npm","package","esm","umd","typed"],"author":{"name":"Gabriel Massadas"},"license":"MIT","_id":"@damazco/email-explorer@1.2.0","maintainers":[{"name":"damazco","email":"ederson@damaz.co"}],"homepage":"https://github.com/damazco-rd/email-explorer","bugs":{"url":"https://github.com/damazco-rd/email-explorer/issues"},"dist":{"shasum":"5880d8298f02029b5f0d2b4aaea20de4a7c34c71","tarball":"https://registry.npmjs.org/@damazco/email-explorer/-/email-explorer-1.2.0.tgz","fileCount":10,"integrity":"sha512-YpeEJUt00Wk5Y032WKHR6dQ4iHUny/IaZytq1iVyuNpXXM/fDep3vAmqm0YwuiFoJWsd8ZuZRaPVQ/UjRvWGNg==","signatures":[{"sig":"MEQCIDt9aizCWaqlo/Jnoe50fG+7IYAm52cbLLqYGvsgQ2swAiBBfaWOD1k1MgizUPdcOKFtUyuVPXWH/Tnh1OU1q75Jmw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":778937},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"d5ed4deed3ef6d60e4cce96ff5861f97313c0e58","scripts":{"test":"tsc && npx vitest run --config tests/vitest.config.mts","build":"tsup src/index.ts --format esm --external cloudflare:workers --external cloudflare:email --dts && cp -R ../dashboard/dist/ dashboard/ && cp ../../README.md . && cp ../../LICENSE .","package":"npm run build && npm pack","publish-npm":"npm publish"},"_npmUser":{"name":"damazco","email":"ederson@damaz.co"},"repository":{"url":"git+https://github.com/damazco-rd/email-explorer.git","type":"git"},"_npmVersion":"10.9.2","description":"A self-hosted, serverless worker for sending and receiving emails on Cloudflare","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.25.76","hono":"4.10.7","chanfana":"2.8.3","workers-qb":"^1.11.2","postal-mime":"^2.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","vitest":"^4.1.9","wrangler":"^4.51.0","typescript":"5.9.3","@types/node":"24.10.1","@cloudflare/workers-types":"^4.20251128.0","@vitest/coverage-istanbul":"^4.1.9","@cloudflare/vitest-pool-workers":"^0.16.20"},"_npmOperationalInternal":{"tmp":"tmp/email-explorer_1.2.0_1782865929351_0.7789063041461954","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"name":"@damazco/email-explorer","version":"1.2.1","description":"A self-hosted, serverless worker for sending and receiving emails on Cloudflare","scripts":{"build":"tsup src/index.ts --format esm --external cloudflare:workers --external cloudflare:email --dts && cp -R ../dashboard/dist/ dashboard/ && cp ../../README.md . && cp ../../LICENSE .","test":"tsc && npx vitest run --config tests/vitest.config.mts","package":"npm run build && npm pack","publish-npm":"npm publish"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","publishConfig":{"access":"public"},"keywords":["cloudflare","worker","workers","serverless","cloudflare email routing","cloudflare email sending","gmail","ui","cf","typescript","npm","package","esm","umd","typed"],"author":{"name":"Gabriel Massadas"},"license":"MIT","homepage":"https://github.com/damazco-rd/email-explorer","repository":{"type":"git","url":"git+https://github.com/damazco-rd/email-explorer.git"},"bugs":{"url":"https://github.com/damazco-rd/email-explorer/issues"},"dependencies":{"chanfana":"2.8.3","hono":"4.10.7","postal-mime":"^2.6.1","workers-qb":"^1.11.2","zod":"^3.25.76"},"devDependencies":{"@cloudflare/vitest-pool-workers":"^0.16.20","@cloudflare/workers-types":"^4.20251128.0","@types/node":"24.10.1","@vitest/coverage-istanbul":"^4.1.9","tsup":"^8.5.1","typescript":"5.9.3","vitest":"^4.1.9","wrangler":"^4.51.0"},"_id":"@damazco/email-explorer@1.2.1","gitHead":"5a0b1b4cbb3696decc519dfb5fe3068a29c3a9ad","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-t0wY5pd7mx6UPvqoF5J96rPh9SCvbBYUy+Wzmsedk9sCzcQOyCY/PqP8RpeloLMGZlY9PeFJWcKJl/scy2Z7fQ==","shasum":"7a9a1da35ce55e91d2bb0ff3ab2f2540ebc3ac2a","tarball":"https://registry.npmjs.org/@damazco/email-explorer/-/email-explorer-1.2.1.tgz","fileCount":10,"unpackedSize":778981,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIApDovPTSWQbEh+dbBb+eXYzu8rGg0xkPYWdM/b+1FG5AiANxmyXw29JoxKUefgEXe2L1iyjHl5OPGvxwH+BFVrhWA=="}]},"_npmUser":{"name":"damazco","email":"ederson@damaz.co"},"directories":{},"maintainers":[{"name":"damazco","email":"ederson@damaz.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/email-explorer_1.2.1_1782869546435_0.14833622773827426"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-01T00:32:09.134Z","modified":"2026-07-01T01:32:26.755Z","1.2.0":"2026-07-01T00:32:09.565Z","1.2.1":"2026-07-01T01:32:26.648Z"},"bugs":{"url":"https://github.com/damazco-rd/email-explorer/issues"},"author":{"name":"Gabriel Massadas"},"license":"MIT","homepage":"https://github.com/damazco-rd/email-explorer","keywords":["cloudflare","worker","workers","serverless","cloudflare email routing","cloudflare email sending","gmail","ui","cf","typescript","npm","package","esm","umd","typed"],"repository":{"type":"git","url":"git+https://github.com/damazco-rd/email-explorer.git"},"description":"A self-hosted, serverless worker for sending and receiving emails on Cloudflare","maintainers":[{"name":"damazco","email":"ederson@damaz.co"}],"readme":"
\n \n

šŸ“§

\n

Email Explorer

\n \n
\n\n

\n A modern, full-stack email client running entirely on Cloudflare Workers\n

\n\n

\n \n \"Email\n \n \n \"Issues\"\n \n \n \"Software\n \n

\n\n# Email Explorer\n\nEmail Explorer is a full-stack, serverless email client that runs entirely on your own Cloudflare account. It provides a modern, fast, and secure way to manage your emails using Cloudflare's powerful infrastructure, including Workers, R2, Durable Objects, Email Routing, and Email Sending.\n\n[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/damazco-rd/email-explorer/tree/main/template)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Why Email Explorer?](#why-email-explorer)\n- [Key Features](#key-features)\n- [Prerequisites](#prerequisites)\n- [Getting Started](#getting-started)\n- [Configuration](#configuration)\n- [Documentation](#documentation)\n- [Architecture](#architecture)\n- [Production Ready Features](#production-ready-features)\n- [Testing](#testing)\n- [Roadmap & Future Enhancements](#roadmap--future-enhancements)\n- [Known Limitations](#known-limitations)\n- [Security](#security)\n- [Contributing](#contributing)\n- [Support](#support)\n- [License](#license)\n\n## Quick Links\n\n- šŸ“– **[User Guides](docs/features/index.md)** - Complete documentation for all features\n- šŸš€ **[Getting Started](#getting-started)** - Deploy in minutes\n- šŸ” **[Authentication](docs/features/authentication.md)** - Setup your first account\n- šŸ”‘ **[Account Recovery](docs/features/account-recovery.md)** - Password reset via email\n- šŸ‘„ **[Admin Panel](docs/features/admin-panel.md)** - Manage users and permissions\n- āš™ļø **[Configuration](#configuration)** - Customize your deployment\n\n## Overview\n\nEmail Explorer gives you a private, self-hosted email solution with a user-friendly web interface. By leveraging the Cloudflare ecosystem, it offers a cost-effective and scalable alternative to traditional email hosting. All your data is stored securely in your own R2 buckets and Durable Objects, giving you full control over your information.\n\n### Screenshots\n\n
\n \"Email\n

Mailbox management and email list view

\n
\n\n
\n \"Email\n

Rich text email composer with formatting options

\n
\n\n## Why Email Explorer?\n\n**šŸ”’ Privacy First**\n- All data stays in YOUR Cloudflare account\n- No third-party tracking or analytics\n- You control your data completely\n\n**šŸ’° Cost-Effective**\n- Runs on Cloudflare's generous free tier\n- Pay only for what you use beyond free limits\n- No monthly subscription fees\n\n**āš” Performance**\n- Built on Cloudflare's global edge network\n- Fast loading times worldwide\n- Serverless architecture scales automatically\n\n**šŸŽØ Modern Experience**\n- Clean, intuitive interface\n- Rich text email composition\n- Mobile-responsive design\n\n**šŸ› ļø Easy Setup**\n- Deploy with one click\n- Automatic mailbox creation\n- Smart authentication setup\n\n> **Note:** To send emails, you need to have [Cloudflare Email Sending](https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/) enabled on your account. Receiving emails works through [Cloudflare Email Routing](https://developers.cloudflare.com/email-routing/).\n\n> **Note:** When you first load your worker, there will be no mailboxes. They are automatically created when you start receiving emails.\n\n## Key Features\n\n- **šŸ”’ Secure & Private**: Self-hosted on your Cloudflare account. No third-party tracking or data scanning.\n- **šŸ” Smart Authentication**: Automatic first-user admin setup with role-based access control and secure session management.\n- **šŸ‘„ Multi-User Support**: Admin panel for managing users and mailbox permissions with granular roles (Owner, Admin, Write, Read).\n- **āœļø Rich Text Editor**: Full-featured WYSIWYG editor with formatting, colors, links, lists, and more - just like Gmail or Outlook.\n- **ā†©ļø Reply & Forward**: Reply to sender, reply all, or forward emails with automatic quoting and threading support.\n- **āœ‰ļø Email Management**: Send, receive, and organize emails with a clean and intuitive interface.\n- **šŸ“ Folder Organization**: Create custom folders to organize your emails.\n- **šŸ“Ž Attachment Support**: View and download attachments directly in the browser.\n- **šŸ” Search**: Find emails quickly with full-text search across all your mailboxes.\n- **šŸ“§ Contacts**: Manage your contacts with an integrated address book.\n- **āš” Serverless Architecture**: Each mailbox is its own Durable Object for optimal performance and isolation.\n\n## Prerequisites\n\nBefore deploying Email Explorer, make sure you have:\n\n- **Cloudflare Account** - [Sign up for free](https://dash.cloudflare.com/sign-up)\n- **Domain Name** - Added to your Cloudflare account\n- **Email Routing** - [Enable Email Routing](https://developers.cloudflare.com/email-routing/) for receiving emails\n- **Email Sending** - [Enable Email Sending](https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/) for sending emails (optional but recommended)\n- **Node.js 18+** - For local development (not required for deployment)\n\n**Cloudflare Services Used:**\n- Workers (Compute)\n- Durable Objects (State management)\n- R2 (Object storage)\n- D1 (SQL database via Durable Objects)\n- Email Routing (Receive emails)\n- Email Sending (Send emails)\n\nMost of these services have generous free tiers that are sufficient for personal use.\n\n## Getting Started\n\nTo deploy Email Explorer, you can use the \"Deploy to Cloudflare\" button above or run this command:\n\n```bash\nnpm create cloudflare@latest -- --template=https://github.com/damazco-rd/email-explorer/tree/main/template\n```\n\n**Or deploy manually:**\n\n```bash\n# Clone the repository\ngit clone https://github.com/damazco-rd/email-explorer.git\ncd email-explorer\n\n# Install dependencies\npnpm install\n\n# Deploy to Cloudflare\npnpm --filter email-explorer deploy\n```\n\n### Configuration\n\nEmail Explorer uses a factory function pattern for configuration. Edit `src/index.ts`:\n\n```typescript\n// Recommended: Smart Mode (Default)\nexport default EmailExplorer({\n auth: {\n enabled: true\n // registerEnabled not specified = smart mode\n },\n accountRecovery: {\n fromEmail: 'noreply@yourdomain.com' // Optional: enable password reset via email\n }\n})\n```\n\n**Smart Mode (Recommended):**\n- First user to register automatically becomes admin\n- Registration closes after first user\n- Admins can create additional users via admin panel\n- Perfect for production deployments\n\n**Other Modes:**\n```typescript\n// Open Registration (Development/Testing)\nexport default EmailExplorer({\n auth: {\n enabled: true,\n registerEnabled: true // Anyone can register\n }\n})\n\n// No Authentication (Single User)\nexport default EmailExplorer({\n auth: {\n enabled: false\n }\n})\n\n// With Account Recovery\nexport default EmailExplorer({\n auth: {\n enabled: true\n },\n accountRecovery: {\n fromEmail: 'noreply@yourdomain.com' // Email address to send password reset links from\n }\n})\n```\n\n**Configuration Options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `auth.enabled` | boolean | `true` | Enable/disable authentication |\n| `auth.registerEnabled` | boolean | `undefined` (smart mode) | Control user registration |\n| `accountRecovery.fromEmail` | string | `undefined` (disabled) | Enable password recovery via email |\n| `provider` | `\"cloudflare\"` \\| `\"resend\"` | `\"cloudflare\"` | Email sending provider |\n\n**Account Recovery:**\n- When configured, users can reset forgotten passwords via email\n- The `fromEmail` address must be a valid email on your Cloudflare account\n- Requires [Cloudflare Email Sending](https://developers.cloudflare.com/email-routing/email-workers/send-email-workers/) to be enabled\n- See [Account Recovery Guide](docs/features/account-recovery.md) for more details\n\n**Email Provider ā€” Resend:**\n\nBy default Email Explorer sends outbound mail through Cloudflare Email Routing. To use [Resend](https://resend.com) instead, set `provider: \"resend\"` and add your API key as a Wrangler secret:\n\n```bash\nnpx wrangler secret put RESEND_API_KEY\n```\n\nThen configure your worker:\n\n```typescript\nexport default EmailExplorer({\n provider: \"resend\",\n auth: { enabled: true }\n})\n```\n\nWhen `provider` is `\"resend\"` the `SEND_EMAIL` Cloudflare binding is not required, so you can omit the `send_email` block from your `wrangler.jsonc` entirely.\n\n### First-Time Setup\n\n1. **Deploy your worker** with smart mode enabled (default)\n2. **Visit your worker URL** in a browser\n3. **Register the first user** - this becomes your admin account\n4. **Log in** with your admin credentials\n5. **Manage additional users** through the admin panel\n\n### Admin Operations\n\nAs an admin, you can:\n- Create new users\n- Grant/revoke mailbox access\n- Assign roles: `owner`, `admin`, `write`, or `read`\n- Promote users to admin status\n\n## Documentation\n\nComprehensive user guides are available for all features:\n\n- **[Feature Documentation](docs/features/index.md)** - Complete user guides\n - [Authentication Guide](docs/features/authentication.md) - Account creation, login, and security\n - [Account Recovery Guide](docs/features/account-recovery.md) - Password reset via email\n - [Admin Panel Guide](docs/features/admin-panel.md) - User management and permissions\n - [Rich Text Editor Guide](docs/features/rich-text-editor.md) - Email formatting and composition\n - [Reply & Forward Guide](docs/features/reply-forward.md) - Email responses and threading\n\nFor developers:\n- **[ROADMAP.md](ROADMAP.md)** - Project roadmap and planned features\n- **[AGENTS.md](AGENTS.md)** - Technical architecture and development guide\n\n## Architecture\n\nEmail Explorer is built with modern web technologies:\n\n**Backend (Worker):**\n- **Hono** - Fast, lightweight web framework\n- **Cloudflare Durable Objects** - Distributed state management\n- **Cloudflare R2** - Object storage for attachments\n- **Cloudflare D1** - SQL database (via Durable Objects)\n- **Cloudflare Email Routing** - Email sending and receiving\n\n**Frontend (Dashboard):**\n- **Vue.js 3** - Progressive JavaScript framework\n- **TypeScript** - Type-safe development\n- **Tailwind CSS** - Utility-first styling\n- **TipTap** - Rich text editor\n- **Pinia** - State management\n- **Vite** - Fast build tooling\n\n## Production Ready Features\n\nāœ… **Authentication & Security**\n- Smart mode with automatic admin setup\n- Session-based authentication (30-day expiry)\n- Password hashing with Web Crypto API\n- HttpOnly, Secure, SameSite cookies\n- Role-based access control (RBAC)\n\nāœ… **Email Capabilities**\n- Send and receive emails\n- Reply and reply-all functionality\n- Forward emails to others\n- Rich text HTML composition\n- Email threading and conversation tracking\n- Attachment handling\n\nāœ… **User Management**\n- Admin panel for user creation\n- Granular mailbox permissions (Owner, Admin, Write, Read)\n- Multi-user support with isolation\n- Access grant and revoke capabilities\n\nāœ… **Organization**\n- Custom folder creation\n- Contact management\n- Full-text email search\n- Email filtering and organization\n\n## Testing\n\nEmail Explorer includes comprehensive integration tests:\n\n```bash\n# Run all tests\npnpm --filter email-explorer test\n\n# Run specific test suite\npnpm --filter email-explorer test auth\npnpm --filter email-explorer test endpoints\n\n# Watch mode for development\npnpm --filter email-explorer test --watch\n```\n\n**Test Coverage:**\n- āœ… Authentication flows (registration, login, sessions)\n- āœ… Admin operations (user management, access control)\n- āœ… Email operations (send, receive, folders)\n- āœ… Search and filtering\n- āœ… Contacts and attachments\n- āœ… Security validations\n\n## Roadmap & Future Enhancements\n\nPlanned features for future releases:\n\n- [ ] Email templates for quick responses\n- [ ] Two-factor authentication (2FA)\n- [ ] Email drafts auto-save\n- [ ] Conversation threading view\n- [ ] Emoji picker in composer\n- [ ] Table support in rich text editor\n- [ ] Image uploads and inline images\n- [x] Email signatures (basic ā€” single signature per mailbox)\n- [ ] Keyboard shortcuts\n- [ ] Mobile app (React Native)\n\nSee [ROADMAP.md](ROADMAP.md) for detailed planning and progress.\n\n## Known Limitations\n\n**Current Limitations:**\n- No email draft auto-save (manual save only)\n- Image uploads not yet supported (URLs work)\n- Single mailbox per user account (multiple access supported)\n\n**Optional Features:**\n- Password reset via email requires `accountRecovery.fromEmail` configuration\n\n**Browser Compatibility:**\n- Modern browsers required (Chrome 90+, Firefox 88+, Safari 14+)\n- JavaScript must be enabled\n- Cookies must be enabled for authentication\n\nPlease report any issues on our [GitHub Issues](https://github.com/damazco-rd/email-explorer/issues) page.\n\n## Security\n\nEmail Explorer takes security seriously:\n\n**šŸ” Authentication Security**\n- Passwords hashed with Web Crypto API (SHA-256)\n- HttpOnly, Secure, SameSite cookies prevent XSS/CSRF\n- 30-day session expiry for automatic logout\n- Session tokens use cryptographic randomness\n\n**šŸ›”ļø Data Protection**\n- All data stored in YOUR Cloudflare account\n- Email content rendered in sandboxed iframes\n- No third-party data sharing\n- Role-based access control (RBAC)\n\n**šŸ”’ Best Practices**\n- Always use HTTPS (automatic with Cloudflare)\n- Keep dependencies updated\n- Regular security audits via GitHub Dependabot\n- Comprehensive test coverage\n\n**āš ļø Security Recommendations**\n- Use strong, unique passwords (8+ characters)\n- Enable Cloudflare's security features\n- Regularly review user access permissions\n- Log out from shared devices\n\n**Report Security Issues:**\nFor security vulnerabilities, please email security issues privately rather than opening public issues.\n\n## Contributing\n\nWe welcome contributions from the community! Here's how you can help:\n\n**šŸ› Bug Reports**\n- Use the [GitHub Issues](https://github.com/damazco-rd/email-explorer/issues) page\n- Include reproduction steps\n- Specify your environment (browser, Cloudflare setup)\n\n**āœØ Feature Requests**\n- Check existing issues first\n- Explain the use case and benefit\n- Consider submitting a PR if you can implement it\n\n**šŸ’» Code Contributions**\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes with tests\n4. Commit your changes (`git commit -m 'Add amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n**šŸ“– Documentation**\n- Help improve user guides\n- Fix typos or clarify instructions\n- Add examples and use cases\n\n**Development Setup:**\n```bash\n# Clone the repository\ngit clone https://github.com/damazco-rd/email-explorer.git\ncd email-explorer\n\n# Install dependencies\npnpm install\n\n# Run tests\npnpm --filter email-explorer test\n\n# Start development\npnpm --filter email-explorer dev\npnpm --filter dashboard dev\n```\n\n## Support\n\n- **šŸ“– Documentation**: Check [docs/features/](docs/features/) for user guides\n- **šŸ’¬ Discussions**: Use GitHub Discussions for questions\n- **šŸ› Issues**: Report bugs via GitHub Issues\n- **šŸ“§ Email**: For security issues only\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Made with ā¤ļø for the self-hosted community**\n\nIf you find Email Explorer useful, please consider giving it a ā­ on GitHub!\n","readmeFilename":"README.md"}