Agentic Inbox

Before deploying or using Agentic Inbox, ensure you have the following:

• A Cloudflare account with a domain.
• Email Routing enabled for receiving.
• Email Service enabled for sending.
• Workers AI enabled (required for the AI agent).
• Cloudflare Access configured (required for production environments).

You can deploy Agentic Inbox using the 'Deploy to Cloudflare' button which automatically provisions R2, Durable Objects, and Workers AI. During the deployment flow, you will be prompted for DOMAINS, which is the domain (e.g., yourdomain.com) you want to receive emails for.

Note: Deployment is only the first step. You must complete the post-deployment configuration (Cloudflare Access, Email Routing, and Email Service) for the application to function correctly.

https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/agentic-inbox

For the inbox to receive and send emails, configure the following in your Cloudflare dashboard:

1. Email Routing (Receiving): Go to your domain > Email Routing and create a catch-all rule that forwards incoming emails to this Worker.
2. Email Service (Sending): The worker requires a send_email binding to send outbound emails. Ensure the Email Service is enabled.

To run Agentic Inbox locally, follow these steps:

1. Install dependencies:

   npm install

2. Run the development server:

   npm run dev

3. Configuration Requirements:
   • Set your domain in wrangler.jsonc.
   • Create an R2 bucket named agentic-inbox using: wrangler r2 bucket create agentic-inbox.

In production environments, the application requires Cloudflare Access for JWT validation. To enable this, you must configure the following environment variables:

• POLICY_AUD: The audience for the Cloudflare Access JWT.
• TEAM_DOMAIN: The domain of your Cloudflare Access team.

Validation is performed using the cf-access-jwt-assertion header. In development (import.meta.env.DEV), this validation is skipped.

The EmailAgent uses a system prompt to define its behavior, writing style, and constraints. By default, it uses a strict DEFAULT_SYSTEM_PROMPT that enforces plain-text replies and prohibits meta-commentary.

Overriding the prompt: You can override the default behavior on a per-mailbox basis by storing a custom prompt in R2. The agent looks for a JSON file at mailboxes/{mailboxId}.json containing an agentSystemPrompt field.

The react-router.config.ts file is used to configure the React Router application. It accepts a configuration object that satisfies the Config type from @react-router/dev/config.

Key configuration options used in this project:

• ssr: A boolean indicating whether Server-Side Rendering is enabled. Set to true to enable SSR.
• future: An object used to enable experimental or upcoming features. In this project, v8_viteEnvironmentApi is set to true to opt into the Vite Environment API.

import type { Config } from "@react-router/dev/config";

export default {
  ssr: true,
  future: {
    v8_viteEnvironmentApi: true,
  },
} satisfies Config;

Once your local configuration is complete, use the following command to deploy the application to Cloudflare:

npm run deploy

Creates a new draft email. It can be a standalone email or a reply-style draft if in_reply_to or thread_id is provided.

Key Options:

• isPlainText: If true, the body is treated as plain text and converted to HTML.
• runVerifyDraft: If true, uses AI to verify/sanitize the body before saving.

Retrieve a list of all available mailboxes configured in the system.

Endpoint: GET /api/v1/mailboxes

The application exports a default fetch handler and an email handler. The email handler is used by Cloudflare Email Routing to process incoming messages using the receiveEmail function.

If receiveEmail fails, the error is re-thrown to ensure Cloudflare's email routing can retry delivery or bounce the message rather than silently dropping it.