Cloudflare Email Sending

Queue-based transactional email sending for Convex apps using Cloudflare Email Service with automatic retries, status tracking, and file attachments.

Installation

npm install @ezyyeah/cloudflare-email-sending

About Cloudflare Email Sending

A durable email sending component that integrates Convex with Cloudflare Email Service using a queue-first architecture. The component handles transactional emails with built-in retry logic, status tracking, and attachment support. Send requests are queued immediately and processed in the background, with exponential backoff for failed deliveries and idempotency protection for duplicate requests.

Benefits

Send emails reliably with automatic exponential backoff retries for network failures and rate limits
Track email status and handle failures gracefully with built-in queue management and cancellation
Attach files from Convex storage or base64 content with automatic size validation
Integrate transactional emails into Convex actions with idempotency key support

Use cases

how to send transactional emails from Convex with retry logic

Use the Cloudflare Email Sending component to queue emails in Convex actions with automatic retries. The component validates requests, handles exponential backoff for failures, and returns an email ID for status tracking.

send email with attachments in Convex application

The component supports attachments from Convex storage IDs or base64 content. It automatically resolves storage files and validates the total message size against Cloudflare's 25 MiB limit before sending.

track email delivery status in Convex

Call getStatus() with the returned email ID to check states like queued, sending, processed, or failed. The component provides acceptance-level tracking and supports cancellation of queued emails.

prevent duplicate emails in Convex with idempotency

Use idempotencyKey in the send request to prevent duplicate emails. The component returns the existing email ID for identical payloads or throws IdempotencyConflictError for different content with the same key.

Frequently asked questions

What Cloudflare setup is required before using this component?

The Cloudflare Email Sending component requires your domain added to Cloudflare DNS, onboarding through the Email Sending dashboard, and waiting for SPF, DKIM, and DMARC DNS propagation. You also need a Cloudflare account ID and API token configured in Convex environment variables.

Does this component guarantee email delivery to inboxes?

No, the Cloudflare Email Sending component provides acceptance-level tracking only. The 'processed' status means Cloudflare accepted the request, not that the email reached the recipient's inbox. Webhook-driven delivery tracking is not currently implemented.

How does retry logic work for failed emails?

The Cloudflare Email Sending component uses exponential backoff with deterministic jitter for retryable failures including network errors, 429 rate limits, and 5xx server errors. Default configuration attempts 5 retries with backoff from 30 seconds to 30 minutes maximum.

Can I send bulk or marketing emails with this component?

The Cloudflare Email Sending component is designed for transactional emails only. It enforces a maximum of 50 recipients per message and focuses on reliable delivery of individual user-triggered emails rather than bulk marketing campaigns.

What file types can be attached to emails?

The Cloudflare Email Sending component supports any file type as attachments, either from Convex storage IDs or base64 encoded content. It validates the total message size stays within Cloudflare's 25 MiB limit and rejects empty filenames or unreadable storage references.