Cloudflare Email Sending

Send through Cloudflare's Email Sending REST API or Worker binding with plain-address recipients and a 50-recipient cap.

Capabilities

Repeated headers	Idempotency	Scheduling	Personalized
No	`none`	No	`expanded`

These values come from the adapter's exported capabilities declaration. The field support matrix covers normalized message fields.

The Cloudflare adapter supports both Cloudflare Worker send_email bindings and Cloudflare's Email Sending REST API. It is the natural pick when your sending domain lives in Cloudflare or when sending directly from a Cloudflare Worker. The trade-off is strict recipient rules: plain addresses only, 50 recipients max.

Cloudflare Email Sending@opencoredev/email-sdk/cloudflare

Provider docs

Configure

Worker binding (Cloudflare Workers)

In a Cloudflare Worker, bind Email Sending in your wrangler.json (or wrangler.toml) and pass the binding object (env.SEB) directly to the adapter.

src/index.ts

import { createEmailClient } from "@opencoredev/email-sdk";
import {
  cloudflare,
  type CloudflareSendEmailBinding,
} from "@opencoredev/email-sdk/cloudflare";

export interface Env {
  SEB: CloudflareSendEmailBinding;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const email = createEmailClient({
      adapters: [
        cloudflare({
          binding: env.SEB,
        }),
      ],
    });

    // ...
  },
};

REST API

Enable Email Sending for your account and domain, then create an API token with Email Sending permission. You also need your account ID.

lib/email.ts

import { createEmailClient } from "@opencoredev/email-sdk";
import { cloudflare } from "@opencoredev/email-sdk/cloudflare";

export const email = createEmailClient({
  adapters: [
    cloudflare({
      apiToken: process.env.CLOUDFLARE_API_TOKEN!,
      accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    }),
  ],
});

Prop

Type

Send

Cloudflare maps cc, bcc, one replyTo, headers, and attachments. There are no tags or metadata.

const result = await email.send({
  from: "Acme Alerts <alerts@acme.com>",
  to: "oncall@example.com",
  cc: "ops@example.com",
  subject: "Disk usage above 90% on db-1",
  text: "db-1 crossed the 90% disk threshold at 14:02 UTC.",
  headers: [{ name: "X-Alert-ID", value: "alrt_8841" }],
});

console.log(result.accepted); // delivered + queued recipients

Cloudflare REST API does not return a message id; instead result.accepted lists delivered and queued recipients and result.rejected lists permanent bounces. Worker bindings return the message ID if provided by the binding. Total recipients across to, cc, and bcc are capped at 50.

Plain recipient addresses only

to, cc, and bcc must be bare addresses like "user@example.com"; a display name throws an EmailValidationError before any request is made. Only from and replyTo keep display names.

Verify from the CLI

CLOUDFLARE_API_TOKEN="..." CLOUDFLARE_ACCOUNT_ID="..." npx --package @opencoredev/email-sdk email-sdk doctor --adapter cloudflare

npx --package @opencoredev/email-sdk email-sdk send \
  --adapter cloudflare \
  --api-token "$CLOUDFLARE_API_TOKEN" \
  --account-id "$CLOUDFLARE_ACCOUNT_ID" \
  --from "Acme <hello@acme.com>" \
  --to user@example.com \
  --subject "Cloudflare smoke test" \
  --text "It works" \
  --dry-run

Drop --dry-run for one real send; only Cloudflare can prove the domain and account are cleared to deliver.

Frequently asked questions

Does Email SDK support Cloudflare?

Yes. Email SDK ships a Cloudflare adapter imported from @opencoredev/email-sdk/cloudflare. You keep your Cloudflare account and credentials; the SDK adds message validation, typed errors, and no-network test adapters around the same send() call used for every other provider.

Which message fields does the Cloudflare adapter support?

Cloudflare supports CC recipients, BCC recipients, Reply-To address, Custom headers, and Attachments. It does not support Tags, Metadata, and Scheduled sending (sendAt); Email SDK rejects a message that uses those fields before any request is made.

Can Cloudflare schedule email for later with Email SDK?

No. Cloudflare has no provider-side scheduling, so a message with sendAt fails validation. Store the job in your own queue and send when it is due.

Does the Cloudflare adapter support idempotent sends?

No. Cloudflare has no provider-side idempotency, so a retried send can be delivered twice. Deduplicate in your own queue before retrying.