cloudflare-email-component

Send, receive, and track email via Cloudflare Email Routing inside a Convex backend, with per-owner message storage and delivery event callbacks.

Installation

npm install @sarant/cloudflare-email-component

About cloudflare-email-component

A Convex component that integrates with Cloudflare Email Sending and Email Routing to send transactional email, track delivery events (bounces, complaints, deliveries), and receive inbound mail through your own Cloudflare account. It persists a record of every message, scoped by owner, and delegates authorization and optional encryption to your application code. Each capability (sending, delivery tracking, inbound routing) is independently opt-in.

Benefits

Send email from Convex actions through Cloudflare Email Sending without managing a separate email service or HTTP client boilerplate.
Track delivery outcomes including bounces, complaints, and suppressions via Cloudflare delivery event webhooks wired directly into your Convex deployment.
Receive inbound mail sent to your domain and handle it in Convex functions using Cloudflare Email Routing worker rules.
Store sent and received messages scoped by owner string so reads and deletes stay authorized without additional indexing work.

Use cases

how to send email from a Convex action using Cloudflare

The cloudflare-email-component exposes a `sendEmail` function you call from a Convex action. It records the message, posts it to the Cloudflare Email Sending API using your account credentials, and stores the result including messageId, delivery status, and any error. It does not throw on Cloudflare refusals, returning structured result fields instead.

how to track email delivery bounces in Convex

The component provides a `recordDeliveryEvents` handler and an `onEvents` callback. After running `setUpDeliveryEvents` once to register a Cloudflare Queue and Worker, Cloudflare posts bounce, complaint, and delivery notifications to your `.convex.site` URL. The component processes them and calls your handler so you can update application state or suppress addresses.

how to receive inbound email in a Convex backend

Using `uploadWorker` and `createRule` from the `@sarant/cloudflare-email-component/cloudflare` entry point, you deploy a Cloudflare Email Routing worker that forwards inbound messages to your Convex deployment's `/email/inbound` endpoint. Your `onReceive` handler is then called with the parsed message so you can store or process it inside Convex functions.

Convex component for Cloudflare email with suppression list

The cloudflare-email-component integrates with Cloudflare's built-in suppression list. If a recipient address is suppressed, Cloudflare rejects the send and the component surfaces that in the `suppressed` result field. Enabling 'Drop suppressed recipients' in the Cloudflare dashboard allows the email to deliver to non-suppressed recipients while still reporting which addresses were dropped.

Frequently asked questions

Does this component work without a Convex backend?

No. The cloudflare-email-component is a Convex component installed via `app.use` and runs exclusively inside a Convex backend. If your app does not use Convex, use Cloudflare's REST API or Workers binding directly instead.

What Cloudflare plan is required to send email to arbitrary addresses?

Sending to any address requires the Cloudflare Workers Paid plan. On the free plan you can only send to verified destination addresses. Email receiving works on both free and paid plans.

Does the cloudflare-email-component store API tokens or email credentials?

No. The component never stores your Cloudflare API token. Credentials are passed via Convex environment variables set with `npx convex env set` and are only used at send time. The `seal` callback lets you encrypt message content before it is stored, so sensitive email body text is also never persisted in plain text unless you choose to.

How does the component handle rate limits or Cloudflare errors?

The cloudflare-email-component retries on 429 and 503 responses twice, after 1 and 3 seconds respectively, since Cloudflare did not send anything in those cases. No other responses are retried because Cloudflare takes no idempotency key and a retry could result in a duplicate send. A send that fails mid-flight is marked as `failed` after 15 minutes.

Can I use the cloudflare-email-component for only sending without setting up delivery tracking or receiving?

Yes. The component is designed in optional layers. You can configure only `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` to get send-only functionality. Delivery event tracking and inbound email receiving are independent features you add by running the respective one-time setup functions when needed.

Links

Components

Open-source building blocks for your Convex app

Browse components in this category.

All All