Noureddine RAMDI / Building a serverless email inbox with Cloudflare Agentic Inbox

Created Mon, 04 May 2026 10:23:02 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1026 Words
github-stars cloudflare email serverless durable-objects typescript self-hosted

cloudflare/agentic-inbox

Building and managing email inboxes that are scalable, secure, and easy to operate remains a challenge for developers. Cloudflare Agentic Inbox takes a different approach by leveraging Cloudflare’s edge platform to host a serverless, stateful email inbox. This reduces infrastructure overhead while enabling persistent state, real-time handling, and integration with Cloudflare’s security and AI capabilities.

What Cloudflare Agentic Inbox does and how it works

Cloudflare Agentic Inbox is an open-source project written in TypeScript designed to run on Cloudflare Workers. It uses Cloudflare Durable Objects to maintain state persistently at the network edge, allowing the inbox to remember messages, sessions, and user settings without external databases.

The architecture tightly integrates several Cloudflare platform features:

  • Durable Objects: These provide stateful storage and coordination for the email inboxes, enabling persistent and consistent state across distributed edge nodes.
  • R2 Object Storage: Used for storing email attachments and larger data blobs.
  • Workers AI: Integrates AI capabilities into the inbox, potentially for automated email processing or other smart features.
  • Cloudflare Email Routing: For receiving and forwarding emails to the Worker.
  • Cloudflare Access: Adds security by restricting inbox access through Access policies and tokens.

The application is deployed as a Cloudflare Worker script that handles incoming HTTP requests and email routing events. The inboxes are created and managed dynamically, supporting multiple mailboxes on custom domains.

This design shifts traditional email server responsibilities to the edge, eliminating the need for dedicated mail servers and complex infrastructure. It leverages Cloudflare’s global network for scalability and performance.

Technical strengths and tradeoffs

One of the standout technical strengths is the use of Durable Objects to maintain state in a serverless environment. Traditional serverless functions are stateless and ephemeral, which complicates building features like sessions or message queues. Durable Objects provide a middle ground by offering persistent, strongly consistent state that lives close to users at the edge.

The repo is written in TypeScript, which provides static typing benefits and better developer tooling. The code quality reflects a modern approach to edge development, adhering to Cloudflare’s best practices.

However, the architecture has clear tradeoffs:

  • Cloudflare dependency: The solution is tightly bound to Cloudflare’s platform and specific services (R2, Durable Objects, Email Routing). This means vendor lock-in and less portability.
  • Configuration complexity: Setting up involves multiple steps, including deploying the Worker, configuring Cloudflare Access, setting secrets, and creating email routing rules. This might be daunting for newcomers.
  • Security reliance: The inbox depends heavily on Cloudflare Access policies for securing email data. Misconfiguration can lead to token errors or exposure risks.

Despite these, the repo demonstrates how to build a real-world application that leverages serverless edge computing beyond simple stateless functions.

How to set up and deploy Cloudflare Agentic Inbox

The project provides a multi-step setup process rather than a single command-line quickstart. Here’s the exact process as documented:

## How to setup

**Important**: Clicking the 'Deploy to Cloudflare' button is only one part of the setup. You must follow the **After deploying** steps as well. For a full step-by-step guide with screenshots, refer to this comment: 
https://github.com/cloudflare/agentic-inbox/issues/4#issuecomment-4269118513

### To set up

1. Deploy to Cloudflare. The deploy flow will automatically provision R2, Durable Objects, and Workers AI. You'll be prompted for **DOMAINS**, which is the domain (yourdomain.com) you want to receive emails for (email@yourdomain.com).

2. **Configure Cloudflare Access** -- Enable one-click Cloudflare Access on your Worker under Settings > Domains & Routes. The modal will show your `POLICY_AUD` and `TEAM_DOMAIN` values. `TEAM_DOMAIN` can be either your Access team URL or the full `.../cdn-cgi/access/certs` URL. **You must set these as secrets for your Worker.**

3. **Set up Email Routing** -- In the Cloudflare dashboard, go to your domain > Email Routing and create a catch-all rule that forwards to this Worker

4. **Enable Email Service** -- The worker needs the `send_email` binding to send outbound emails. See Email Service docs

5. **Create a mailbox** -- Visit your deployed app and create a mailbox for any address on your domain (e.g. `hello@example.com`)

### Troubleshooting Access

1. If you see `Invalid or expired Access token`, that usually means `POLICY_AUD` or `TEAM_DOMAIN` secrets are incorrect.
   * Resolution: turn Access off and back on for the Worker to get the Access modal again, then reset your Worker secrets to the latest `POLICY_AUD` and `TEAM_DOMAIN` values shown there.
2. If you see `Cloudflare Access must be configured in production`, this application is intentionally enforcing Cloudflare Access so your inbox is not exposed to anyone on the internet.
   * Resolution: enable Access using one-click Cloudflare Access for Workers, then set the `POLICY_AUD` and `TEAM_DOMAIN` Worker secrets from the modal values.

The setup flow highlights the deep integration with Cloudflare services and the necessary understanding of Cloudflare Access and Email Routing to get the inbox operational.

verdict

Cloudflare Agentic Inbox is a solid example of building a serverless, stateful email inbox on the edge. It’s particularly relevant for developers and teams already invested in the Cloudflare ecosystem who want to offload mail server complexity to a scalable, managed platform.

The tradeoff is the reliance on Cloudflare’s proprietary services, which may not suit everyone. Also, the setup has a non-trivial learning curve, especially around Access configuration and email routing.

If your goal is to experiment with serverless Durable Objects for stateful applications or build a Cloudflare-native email solution, this repo is worth exploring. For others looking for a more platform-agnostic or turnkey email server, traditional email solutions or other self-hosted projects might be more appropriate.

Overall, the repo offers a practical demonstration of how far serverless edge computing can go beyond stateless functions, enabling real-world applications like email inboxes with persistent state and integrated security.

→ GitHub Repo: cloudflare/agentic-inbox ⭐ 2,456 · TypeScript