Zotlyx Inbox

Professional shared inbox workspace for teams, built on Cloudflare Workers.

Zotlyx Inbox is a self-hosted team inbox application for shared mailbox operations such as info@, support@, and sales@. It combines a modern mailbox UI, role-based access control, real-time updates, and an integrated AI assistant while keeping the full deployment inside your own Cloudflare account.

Incoming mail is handled through Cloudflare Email Routing, each mailbox is isolated inside its own Durable Object with SQLite storage, attachments are stored in R2, and the AI features run on Workers AI.

Zotlyx Inbox is inspired by and adapted from Cloudflare's Agentic Inbox, with additional product, UX, and operational changes for team mailbox usage.

Screenshots

Inbox

Dashboard

Documentation

For practical product usage and setup instructions, use the docs folder:

• Documentation index
• Getting started
• Admin guide
• Mailbox guide
• Email setup
• Troubleshooting

Why this project

Zotlyx Inbox is designed for teams that want:

• A clean shared inbox instead of forwarding everything into personal mailboxes
• Fine-grained access control for users and groups
• Real-time inbox updates without manual refresh
• A lightweight AI agent that can read, search, and draft replies
• Full control over the infrastructure, data, and deployment

One-click deploy

You can deploy the application directly from GitHub with Cloudflare's deploy flow:

What the deploy button does

• Creates the Worker from this repository
• Provisions the configured Cloudflare resources used by the app
• Lets you set the required secrets for the first admin login

After the deploy completes, the app will automatically initialize its D1 tables on first run, so you can sign in right away without running any manual migration commands.

What still needs to be done after deploy

Cloudflare email infrastructure still needs a short guided setup after the app is deployed:

1. Configure your domain in Cloudflare
2. Set up Email Routing for inbound mail
3. Enable Email Service for outbound sending
4. Open the app and sign in with the bootstrap admin account
5. Add your domain, users, groups, and shared mailboxes

This means the app is deployable in one click, but email routing and sender configuration still require Cloudflare dashboard setup.

Core capabilities

• Shared mailbox operations: inbox, sent, drafts, archive, trash, spam, search, threading, reply, and forward
• Team access control: assign mailbox access directly to users or through groups
• Real-time mailbox updates: SSE-based live refresh for new emails, read state, draft updates, and thread changes
• AI side panel: search conversations, read thread context, and draft replies with a mailbox-aware agent
• Mailbox isolation: every mailbox runs in its own Durable Object with isolated SQLite state
• Attachment handling: upload, preview, and download via R2
• Audit visibility: administrative actions and mailbox activity can be tracked from the admin side

Tech stack

• Frontend: React 19, React Router v7, Tailwind CSS, Zustand, TipTap, @cloudflare/kumo
• Backend: Hono, Cloudflare Workers, Durable Objects, D1, R2
• Realtime: Server-Sent Events
• AI: Cloudflare Agents SDK, AI SDK v6, Workers AI
• Authentication: email/password sessions with PBKDF2 password hashing

Architecture

┌──────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Browser    │────>│  Hono Worker     │────>│  MailboxDO      │
│  React SPA   │     │  (API + SSR)     │     │  (SQLite + R2)  │
│  Agent Panel │     │                  │     └─────────────────┘
└──────┬───────┘     │  /agents/* ──────┼────>┌─────────────────┐
       │             │                  │     │  EmailAgent DO  │
       │ SSE         │                  │     │  AI draft tools │
       └─────────────┤                  │────>│  Workers AI     │
                     └──────────────────┘     └─────────────────┘

Prerequisites

Before running the app, make sure you have:

• A Cloudflare account
• A domain connected to Cloudflare
• Email Routing enabled for receiving mail
• Email Service enabled for outbound sending
• Workers AI enabled if you want the AI agent features
• pnpm and Node.js 20+

Local development

1. Install dependencies

pnpm install

Developer migrations (optional)

This project auto-initializes its D1 tables on first run, so most users do not need to run migrations manually.

If you are developing the project and want to apply a schema change explicitly:

1. Add a new SQL file under workers/db/migrations/ (e.g. 0003_add_feature.sql)
2. Apply migrations locally:

pnpm exec wrangler d1 migrations apply zotlyx-inbox-db --local

3. Apply migrations to production:

pnpm exec wrangler d1 migrations apply zotlyx-inbox-db --remote

Important:

• The --remote command must target the same D1 database that is bound to the Worker under the DB binding (Cloudflare dashboard → Workers & Pages → your Worker → Bindings).

2. Create infrastructure

Create the R2 bucket:

pnpm exec wrangler r2 bucket create zotlyx-inbox

Create the D1 database:

pnpm exec wrangler d1 create zotlyx-inbox-db

3. Create local secrets

Create .dev.vars in the project root:

ADMIN_BOOTSTRAP_EMAIL="admin@yourdomain.com"
ADMIN_BOOTSTRAP_PASSWORD="change-this-password"

On first boot, the application seeds the first administrator account automatically.

4. Start development

pnpm run dev

Production deployment

1. Set Cloudflare secrets

pnpm exec wrangler secret put ADMIN_BOOTSTRAP_EMAIL
pnpm exec wrangler secret put ADMIN_BOOTSTRAP_PASSWORD

2. Deploy

pnpm run deploy

First-run checklist

After deployment, use this checklist to finish production setup:

1. Sign in with the bootstrap admin account
2. Open the app once to let it auto-initialize the D1 schema (tables are created automatically)
3. Open Cloudflare Email Routing and point inbound mail to the Worker
4. Enable outbound sending in Cloudflare Email Service
5. Add your domain in the app
6. Create shared mailboxes such as info@, support@, or sales@
7. Grant mailbox access to users or groups
8. Send and receive a real test email before inviting the team

Manual Cloudflare email setup

Domain onboarding is intentionally manual in the app. After deployment:

Inbound mail (receive) — Email Routing

1. Open your domain in the Cloudflare dashboard
2. Go to Email Routing → Routing rules
3. Create a rule and set the action to Send to Worker → select your deployed Worker (e.g. zotlyx-inbox)
4. Enable the rule

Recommended rules:

• Catch-all: *@yourdomain.com → Worker (useful for team inboxes like info@, support@, sales@)
• Mailbox-specific: support@yourdomain.com → Worker (if you only want to route specific addresses)

Important:

• If the routing rule is disabled, inbound email will not arrive and you may see bounces like 550 5.1.1 Address does not exist.
• The app only shows mail for mailboxes you created in the UI. Create the mailbox first, then send a test email to it.

Outbound mail (send) — Email Service

1. Go to Email Service / Email Sending
2. Enable onboarding for your domain (e.g. yourdomain.com)
3. Complete the required DNS records and verification steps shown in the dashboard
4. In the app, send emails from addresses under the onboarded domain (example: support@yourdomain.com)

Notes:

• Email Service is intended for transactional messages (replies, notifications) rather than marketing/bulk email.
• If Cloudflare shows recipient restrictions in your account, you may need to verify destination addresses while testing.

The app manages mailboxes and access control, but Cloudflare dashboard configuration remains the source of truth for routing and sender setup.

Admin workflow

Recommended setup order for a fresh workspace:

1. Register the domain in the app
2. Create users
3. Create groups if needed
4. Create shared mailboxes
5. Grant mailbox access to users or groups
6. Start using the mailbox UI from the dashboard

Operational notes

• Delete from normal folders moves mail to Trash
• Delete from Trash removes mail permanently
• Non-admin users only see mailboxes they have access to
• Real-time updates use SSE, so you will see a long-lived event connection in DevTools
• The AI assistant helps with reading and drafting, but sending still stays explicit and user-controlled

Useful commands

pnpm run dev
pnpm run build
pnpm run deploy
pnpm run preview
pnpm run typecheck
pnpm exec wrangler whoami

Upgrade note

If you are upgrading from an older single-tenant version:

1. Deploy the latest code and open the app once to let it auto-initialize any missing D1 tables
2. Sign in with the bootstrap admin account
3. Re-check mailbox access assignments
4. Verify that existing mailboxes have matching access rows for employee visibility

Related reading

• Cloudflare Email Routing
• Cloudflare Email Service
• Cloudflare Durable Objects
• Cloudflare Workers AI
• Cloudflare Agents SDK
• Email for Agents blog post

Inspiration and credit

Zotlyx Inbox is inspired by and adapted from Cloudflare's Agentic Inbox.

This project keeps its own branding, product direction, and custom implementation work, while acknowledging the original open-source foundation and ideas from Cloudflare's project.

Support the project

If this project helps you and you want to support ongoing development, add your official Buy Me a Coffee link here:

• Buy Me a Coffee: https://buymeacoffee.com/muhammadsujon

Current maintainer:

• Muhammad Sujon
• GitHub: developer-sujon
• Email: muhammad.sujon.cse@gmail.com

License

Apache 2.0. See LICENSE.