Cloudflare Email

The Cloudflare Email transport is an official Better-Notify package that sends email through the Cloudflare Email Service REST API. Use it when you are already on Cloudflare and want transactional email without an external provider.

It uses plain fetch() with zero external dependencies, so it works in Node.js, Bun, Cloudflare Workers, and any runtime with a global fetch.

Install

npm install @betternotify/cloudflare-email @betternotify/core @betternotify/email

Getting your credentials

You need two values: an API token and your account ID.

API token

1. Go to API Tokens in your Cloudflare dashboard.
2. Click Create Token.
3. Select Create Custom Token.
4. Under Permissions, set Account > Email Sending > Edit.

5. Click Continue to summary, then Create Token.
6. Copy the token — you will not see it again.

Account ID

1. Go to your Cloudflare dashboard home page.
2. Click the three-dot menu (⋮) next to your account name.
3. Select Copy account ID.

Store both values as environment variables:

CF_ACCOUNT_ID=your-account-id
CF_API_TOKEN=your-api-token

Usage

import { createNotify, createClient } from '@betternotify/core';
import { emailChannel } from '@betternotify/email';
import { cloudflareEmailTransport } from '@betternotify/cloudflare-email';

const email = emailChannel({
  defaults: { from: { name: 'My App', email: 'noreply@example.com' } },
});

const rpc = createNotify({ channels: { email } });
const catalog = rpc.catalog({
  /* routes */
});

const mail = createClient({
  catalog,
  transportsByChannel: {
    email: cloudflareEmailTransport({
      accountId: process.env.CF_ACCOUNT_ID!,
      apiToken: process.env.CF_API_TOKEN!,
    }),
  },
});

Options

Error handling

The transport maps Cloudflare error codes to Better-Notify error codes:

Network failures and unparseable responses are wrapped as PROVIDER errors.

Attachments

The transport base64-encodes attachment content and infers the disposition from the cid field:

• If cid is set, the attachment is sent as inline with a contentId.
• Otherwise it is sent as attachment.
• If contentType is not set, it defaults to application/octet-stream.

Limits

These limits are enforced by Cloudflare, not by the transport:

• 50 recipients per email (to + cc + bcc combined)
• 5 MiB total message size (25 MiB for verified addresses)
• 998 characters subject line (RFC 5322)
• 16 KB custom headers
• Daily sending limits vary by account standing

If you need throttling or provider fallback, add withRateLimit middleware or wrap the transport in multiTransport({ strategy: 'failover' }).