Email Routing

API reference for Cloudflare Email Routing

Overview

Cloudflare Email Routing allows you to create custom email addresses for your domain and route them to your preferred email inbox. Manage routing rules, destination addresses, and DNS records.

Initialize the client

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: 'your-api-token',
});

Settings

Manage Email Routing settings for a zone.

Get settings

Get information about Email Routing settings for your zone.

const settings = await client.emailRouting.get({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

zone_id · string · required

Zone identifier

id · string

Email Routing settings identifier

enabled · boolean

State of Email Routing (enabled or disabled)

name · string

Domain of your zone

status · string

Account status: ready, unconfigured, misconfigured, misconfigured/locked, or unlocked

created · string

When the settings were created

modified · string

When the settings were last modified

skip_wizard · boolean

Whether the user skipped the configuration wizard

Enable Email Routing (deprecated)

Enable Email Routing for your zone. This adds and locks necessary MX and SPF records.

const settings = await client.emailRouting.enable({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  body: {},
});

Disable Email Routing (deprecated)

Disable Email Routing for your zone. This removes additional MX records.

const settings = await client.emailRouting.disable({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  body: {},
});

Rules

Manage email routing rules.

Create a rule

Create a new routing rule.

const rule = await client.emailRouting.rules.create({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
  matchers: [
    {
      type: 'literal',
      field: 'to',
      value: '[e-mail]',
    },
  ],
  actions: [
    {
      type: 'forward',
      value: ['[e-mail]'],
    },
  ],
});

zone_id · string · required

Zone identifier

matchers · array · required

Matching rules to filter emails

actions · array · required

Actions to perform on matched emails

enabled · boolean

Whether the rule is enabled (default: true)

name · string

Rule name

priority · number

Rule priority (lower values execute first)

Update a rule

Update an existing routing rule.

const rule = await client.emailRouting.rules.update(
  ruleId,
  {
    zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
    // updated fields
  }
);

List rules

List all routing rules for a zone.

const rules = await client.emailRouting.rules.list({
  zone_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Get a rule

Get details of a specific routing rule.

const rule = await client.emailRouting.rules.get(
  ruleId,
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete a rule

Delete a routing rule.

await client.emailRouting.rules.delete(
  ruleId,
  { zone_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Addresses

Manage destination email addresses.

Create an address

Add a verified destination address.

const address = await client.emailRouting.addresses.create({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
  email: '[e-mail]',
});

account_id · string · required

Account identifier

email · string · required

The email address to verify and use as a destination

List addresses

List all verified destination addresses.

const addresses = await client.emailRouting.addresses.list({
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
});

Get an address

Get details of a destination address.

const address = await client.emailRouting.addresses.get(
  addressId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

Delete an address

Remove a destination address.

await client.emailRouting.addresses.delete(
  addressId,
  { account_id: '023e105f4ecef8ad9ca31a8372d0c353' }
);

DNS

Manage DNS records for Email Routing.

const dns = client.emailRouting.dns;

The DNS resource provides methods for managing MX and other DNS records required for Email Routing.

Types

Matcher

Defines how to match incoming emails.

type · 'literal' | 'all'

Matcher type

field · 'to' | 'from'

Email field to match against

value · string

Value to match (for literal matchers)

Action

Defines what to do with matched emails.

type · 'forward' | 'worker' | 'drop'

Action type

value · string[]

Destination addresses (for forward action)

EmailRoutingRule

id · string

Rule identifier

tag · string

Rule tag

name · string

Rule name

enabled · boolean

Whether the rule is active

matchers · Matcher[]

Matching conditions

actions · Action[]

Actions to perform

priority · number

Rule priority