Cloudflare Email Sending Integration

Cloudflare Email Sending is an email delivery service provided by Cloudflare, ideal for projects whose domains are already hosted on Cloudflare. Compared to Resend, it does not require signing up for an additional third-party email provider and integrates seamlessly with Cloudflare's domain and DNS management.

In the NEXTY.DEV boilerplate, email sending is abstracted behind a unified lib/mail entry. You can switch between Resend and Cloudflare Email Sending via environment variables without changing any business code.

Prerequisites

• A Cloudflare account with your domain already hosted on Cloudflare.
• If you deploy on Cloudflare Workers, refer to the email binding approach in the cf-pg branch. This document covers server deployments or Vercel deployments that use the Cloudflare SDK REST API to send emails.

Configure Your Domain

Log in to the Cloudflare dashboard, type "email sending" in the top search bar, and open the Email Sending page.

Click to start connecting your domain and follow the prompts to select the domain you want to use.

After the domain is added, click it to enter the details page, then click Connect to finish the connection.

Once connected, Cloudflare will show you the DNS records you need to add (such as SPF, DKIM, DMARC, etc.). Follow the dashboard instructions to add these records on the DNS page of the corresponding domain until the Email Sending status shows as available.

Create an API Token

To send emails through the Cloudflare Email Sending REST API, you need to create a dedicated API Token.

1. Open the Cloudflare API Tokens page and click Create Token.
2. Select Create Custom Token.

3. Fill in the form with the following rules:

   • Token name: Custom, e.g. nexty-email-sending.
   • Permissions:
     • Account → Email Sending → Edit
     • Zone → Email Routing Rules → Edit
   • Account Resources:
     • Include → Select the current account
   • Zone Resources:
     • Include → Specific zone → Select the current domain

4. Copy the generated Token.
5. Find the Account ID on the right side of the Cloudflare dashboard and copy it.

Configure Environment Variables

Fill the information obtained in the previous step into the environment variables:

# Email provider: resend or cloudflare, defaults to resend
DEFAULT_EMAIL_PROVIDER=cloudflare
 
# Sender info, shared by Resend and Cloudflare
DEFAULT_ADMIN_EMAIL=[email protected]
DEFAULT_ADMIN_NAME="Your App Name"
 
# Cloudflare Email Sending specific
CLOUDFLARE_EMAIL_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id

• DEFAULT_EMAIL_PROVIDER: Optional resend or cloudflare, controls the default provider used by lib/mail.
• DEFAULT_ADMIN_EMAIL: Sender email address. Must be a domain email that has been verified by Cloudflare Email Sending.
• DEFAULT_ADMIN_NAME: Sender display name.
• CLOUDFLARE_EMAIL_API_TOKEN: The API Token created above.
• CLOUDFLARE_ACCOUNT_ID: Cloudflare account ID.

Send Emails in Code

Business code sends emails through sendEmail from lib/mail without worrying about whether the underlying provider is Resend or Cloudflare.

import { sendEmail } from "@/lib/mail";
import { NewsletterWelcomeEmail } from "@/emails/newsletter-welcome";
 
const result = await sendEmail({
  to: "[email protected]",
  from: {
    email: process.env.DEFAULT_ADMIN_EMAIL!,
    name: process.env.DEFAULT_ADMIN_NAME || "Your App Name",
  },
  subject: "Welcome to our service!",
  react: NewsletterWelcomeEmail,
  reactProps: {
    email: "[email protected]",
    unsubscribeLink: "https://yourdomain.com/unsubscribe?token=xxx",
  },
  headers: {
    "List-Unsubscribe": "<https://yourdomain.com/unsubscribe?token=xxx>",
  },
  addToContacts: true,
});
 
if (!result.success) {
  console.error("Send email failed:", result.error);
}

If you need to explicitly specify a provider (for example, for A/B testing or sending through both providers at the same time), use the second parameter:

import { sendEmail } from "@/lib/mail";
 
// Explicitly use Cloudflare
await sendEmail({ ...options }, "cloudflare");
 
// Explicitly use Resend
await sendEmail({ ...options }, "resend");

Use the Cloudflare SDK Directly

If your product needs to bypass the default provider set by environment variables, you can use the Cloudflare SDK directly:

import Cloudflare from "cloudflare";
 
const client = new Cloudflare({
  apiToken: process.env.CLOUDFLARE_EMAIL_API_TOKEN,
});
 
const response = await client.emailSending.send({
  account_id: process.env.CLOUDFLARE_ACCOUNT_ID!,
  from: "[email protected]",
  to: "[email protected]",
  subject: "Welcome to our service!",
  html: "<h1>Welcome!</h1><p>Thanks for signing up.</p>",
  text: "Welcome! Thanks for signing up.",
});

Recommended practice

Always use sendEmail from lib/mail so that contact management, retries, React template rendering, and text fallback are handled automatically by the boilerplate.

Contact Management Notes

• When the default provider is Resend, after an email is sent successfully the recipient is added to both Resend Contacts and a Redis contact set.
• When the default provider is Cloudflare, because Cloudflare Email Sending currently does not provide a contacts API, the recipient is only recorded in the Redis contact set.
• The unsubscribe logic (removeContact) cleans up both Resend Contacts and Redis records at the same time, ensuring unsubscribe remains effective after switching providers.

Verification

After configuration, you can verify by:

1. Setting the above environment variables correctly in your local or preview environment.
2. Visiting the email subscription input box in the website footer, entering a test email address, and submitting.
3. Checking whether the test inbox receives the welcome email.
4. Logging in to the Cloudflare dashboard, opening the Email Sending page, and reviewing send logs and status.

Notes

• Cloudflare Email Sending requires the sender domain to have passed DNS verification; otherwise emails will be rejected.
• The Cloudflare email implementation in the current main branch is based on the REST API and is suitable for Node.js servers or Vercel deployments. If you deploy natively on Cloudflare Workers, use the cf-pg branch, which implements internal communication through the send_email binding.
• If you have configured both Resend and Cloudflare environment variables, you can switch between them at any time via DEFAULT_EMAIL_PROVIDER without changing business code.