Cloudflare API | Email Routing › Rules › Create Routing Rule

API Reference

Account & User Management

Resource Sharing

AI

Certificate Management

Certificate Authorities

Client Certificates

Custom Certificates

Custom Hostnames

Keyless Certificates

MTLS Certificates

Origin CA Certificates

Origin Post Quantum Encryption

Origin TLS Client Auth

Cloudflare One

DNS

Account Custom Nameservers

Domain/Zone Management

IP Addresses

Media

Networking

Magic Network Monitoring

Observability

Radar

Rules

Cloud Connector

Managed Transforms

URL Normalization

Security

Content Scanning

Leaked Credential Checks

Storage & Databases

Threat Intelligence

Brand Protection

Workers & Pages

Durable Objects

Workers For Platforms

Shared

Email Routing

email_routing

Methods

Disable Email Routing -> Envelope<

>

post/zones/{zone_id}/email/routing/disable

Disable your Email Routing zone. Also removes additional MX records previously required for Email Routing to work.

Enable Email Routing -> Envelope<

>

post/zones/{zone_id}/email/routing/enable

Enable you Email Routing zone. Add and lock the necessary MX and SPF records.

Get Email Routing Settings -> Envelope<

>

get/zones/{zone_id}/email/routing

Get information about the settings for your Email Routing zone.

Domain types

Settings = { id, enabled, name, 5 more... }

Addresses

email_routing.addresses

Methods

Create A Destination Address -> Envelope<

>

post/accounts/{account_id}/email/routing/addresses

Create a destination address to forward your emails to. Destination addresses need to be verified before they can be used.

Delete Destination Address -> Envelope<

>

delete/accounts/{account_id}/email/routing/addresses/{destination_address_identifier}

Deletes a specific destination address.

Get A Destination Address -> Envelope<

>

get/accounts/{account_id}/email/routing/addresses/{destination_address_identifier}

Gets information for a specific destination email already created.

List Destination Addresses -> V4PagePaginationArray<

>

get/accounts/{account_id}/email/routing/addresses

Lists existing destination addresses.

Domain types

Address = { id, created, email, 3 more... }

DNS

email_routing.dns

Methods

Enable Email Routing -> Envelope<

>

post/zones/{zone_id}/email/routing/dns

Enable you Email Routing zone. Add and lock the necessary MX and SPF records.

Disable Email Routing -> { errors, messages, success } | { errors, messages, success, 2 more... }

delete/zones/{zone_id}/email/routing/dns

Disable your Email Routing zone. Also removes additional MX records previously required for Email Routing to work.

Unlock Email Routing -> Envelope<

>

patch/zones/{zone_id}/email/routing/dns

Unlock MX Records previously locked by Email Routing.

Email Routing DNS Settings -> { errors, messages, success, 2 more... } | { errors, messages, success, 2 more... }

get/zones/{zone_id}/email/routing/dns

Show the DNS records needed to configure your Email Routing zone.

Domain types

DNSRecord = { content, name, priority, 2 more... }

Rules

email_routing.rules

Methods

Create Routing Rule -> Envelope<

EmailRoutingRule

>

post/zones/{zone_id}/email/routing/rules

Rules consist of a set of criteria for matching emails (such as an email being sent to a specific custom email address) plus a set of actions to take on the email (like forwarding it to a specific destination address).

Security

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example: X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example: X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Parameters

zone_id: string

Identifier

Response fields

errors: Array<

>

messages: Array<

>

success: true

Whether the API call was successful

result:

EmailRoutingRule

Optional

Request example

curl https://api.cloudflare.com/client/v4/zones/$ZONE_ID/email/routing/rules \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{
      "actions": [
        {
          "type": "drop",
          "value": [
            "destinationaddress@example.net"
          ]
        }
      ],
      "matchers": [
        {
          "field": "to",
          "type": "literal",
          "value": "test@example.com"
        }
      ],
      "enabled": true,
      "name": "Send to user@example.net rule."
    }'

200Example

{
  "errors": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message"
    }
  ],
  "success": true,
  "result": {
    "id": "a7e6fb77503c41d8a7f3113c6918f10c",
    "actions": [
      {
        "type": "drop",
        "value": [
          "destinationaddress@example.net"
        ]
      }
    ],
    "enabled": true,
    "matchers": [
      {
        "field": "to",
        "type": "literal",
        "value": "test@example.com"
      }
    ],
    "name": "Send to user@example.net rule.",
    "priority": 0,
    "tag": "a7e6fb77503c41d8a7f3113c6918f10c"
  }
}

Delete Routing Rule -> Envelope<

EmailRoutingRule

>

delete/zones/{zone_id}/email/routing/rules/{rule_identifier}

Delete a specific routing rule.

Get Routing Rule -> Envelope<

EmailRoutingRule

>

get/zones/{zone_id}/email/routing/rules/{rule_identifier}

Get information for a specific routing rule already created.

List Routing Rules -> V4PagePaginationArray<

EmailRoutingRule

>

get/zones/{zone_id}/email/routing/rules

Lists existing routing rules.

Update Routing Rule -> Envelope<

EmailRoutingRule

>

put/zones/{zone_id}/email/routing/rules/{rule_identifier}

Update actions and matches, or enable/disable specific routing rules.

Domain types

Action = { type, value }

EmailRoutingRule = { id, actions, enabled, 4 more... }

Matcher = { field, type, value }

Email Routing Rules

Catch Alls

email_routing.rules.catch_alls

Methods

Get Catch All Rule -> Envelope<{ id, actions, enabled, 3 more... }>

get/zones/{zone_id}/email/routing/rules/catch_all

Get information on the default catch-all routing rule.

Update Catch All Rule -> Envelope<{ id, actions, enabled, 3 more... }>

put/zones/{zone_id}/email/routing/rules/catch_all

Enable or disable catch-all routing rule, or change action to forward to specific destination address.

Domain types

CatchAllAction = { type, value }

CatchAllMatcher = { type }