[Skip to content](#main)

[→](/)

[![Avunu](/brand/avunu-logo.svg)![Avunu](/brand/avunu-logo-light.svg)](/)[Services](/services/)[Consulting](/services/consulting/)[ERP](/services/erp/)[Odoo](/services/erp/odoo/)[ERPNext](/services/erp/erpnext/)[Custom software](/services/custom-software/)[Devices & IoT](/services/devices-iot/)[Websites](/services/websites/)[Infrastructure](/services/infrastructure/)[Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

[About Avunu](/about/)[Team](/about/team/)[Insights](/insights/)[Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

- [Services](/services/)[Consulting](/services/consulting/)
- [ERP](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)
- [Partners](/partners/)

[Work](/work/)[Open source](/open-source/)[Knowledge base](/kb/)[About](/about/)

- [About Avunu](/about/)
- [Team](/about/team/)
- [Insights](/insights/)
- [Contact](/contact/)

[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

[Knowledge base](/kb/)[Email](/kb/email/)Send and receive Frappe and ERPNext email through Cloudflare

Search the knowledge basePress/

ESC

Jump to

[Browse the knowledge base](/kb/)[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Email](/kb/email/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

↵select↑↓navigateescclose

Search the knowledge base

[Skip to the article](#kb-article)[Email](/kb/email/)6 articles

- [Overview](/kb/email/)
- [Deploy the cloudflare-email-relay Worker](/kb/email/deploying-cloudflare-email-relay/)
- [Email without SMTP for business systems](/kb/email/email-without-smtp-for-business-systems/)
- [Send and receive Frappe and ERPNext email through Cloudflare](/kb/email/cloudflare-email-for-frappe-and-erpnext/)
- [Send and receive Odoo email through Cloudflare](/kb/email/cloudflare-email-for-odoo/)
- [Send WordPress email through Cloudflare Email Sending](/kb/email/cloudflare-email-for-wordpress/)
- [Troubleshooting Cloudflare email delivery](/kb/email/troubleshooting-cloudflare-email/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

In Email: 6 articles

[Overview](/kb/email/)[Deploy the cloudflare-email-relay Worker](/kb/email/deploying-cloudflare-email-relay/)[Email without SMTP for business systems](/kb/email/email-without-smtp-for-business-systems/)[Send and receive Frappe and ERPNext email through Cloudflare](/kb/email/cloudflare-email-for-frappe-and-erpnext/)[Send and receive Odoo email through Cloudflare](/kb/email/cloudflare-email-for-odoo/)[Send WordPress email through Cloudflare Email Sending](/kb/email/cloudflare-email-for-wordpress/)[Troubleshooting Cloudflare email delivery](/kb/email/troubleshooting-cloudflare-email/)

Other sections[Frappe](/kb/frappe/)[ERPNext](/kb/erpnext/)[Odoo](/kb/odoo/)[WordPress](/kb/wordpress/)[NixOS](/kb/nixos/)[Linux](/kb/linux/)[Databases](/kb/databases/)[Containers](/kb/containers/)[Proxmox](/kb/proxmox/)[Git & Dev Tools](/kb/git-and-dev-tools/)

EmailSend and receive Frappe and ERPNext email through Cloudflare

Install cloudflare_email_delivery to send Frappe email through the Cloudflare Email Sending API and receive it through a signed webhook, with no SMTP or IMAP.

UpdatedOct 5, 2026

Applies toFrappe v16cloudflare_email_delivery 0.1.0Python 3.12

Tagsemailcloudflarefrappeerpnext

Reading time11 min

On this page[How it works](#how-it-works)[Requirements](#requirements)[Install the app](#install-the-app)[Configure outbound](#configure-outbound)[Create the Email Domain](#create-the-email-domain)[Create the Email Account](#create-the-email-account)[What gets sent](#what-gets-sent)[Retries and failures](#retries-and-failures)[Configure inbound](#configure-inbound)[Enable incoming on the Email Account](#enable-incoming-on-the-email-account)[Set host_name first](#set-host_name-first)[Hand the credentials to the relay](#hand-the-credentials-to-the-relay)[Rotate the secret](#rotate-the-secret)[Test inbound](#test-inbound)[The webhook contract](#the-webhook-contract)[How replies thread](#how-replies-thread)[Limits and known gaps](#limits-and-known-gaps)[Troubleshoot](#troubleshoot)[Run the tests](#run-the-tests)[Related documents](#related-documents)

This document shows how to run Frappe or ERPNext email entirely through Cloudflare with the `cloudflare_email_delivery` app. Use it when you want to retire SMTP and IMAP credentials for a domain and let Cloudflare carry both directions. For the design behind it, read [Email Without SMTP for Business Systems](/kb/email/email-without-smtp-for-business-systems/) first.

## How it works

The app replaces two things Frappe normally does with mailbox servers.

**Outbound.** Frappe's `override_email_send` hook hands every Email Queue entry to the app. For an account on a Cloudflare domain, the app makes one call to the Cloudflare Email Sending REST API per recipient. Accounts on other domains keep using SMTP or Frappe Mail as before.

**Inbound.** Cloudflare Email Routing delivers mail to a relay Worker ([`cloudflare-email-relay`](https://github.com/Avunu/cloudflare-email-relay)). The Worker posts each message to your site as a signed HTTPS request. The app verifies the signature and gives the raw message to Frappe's own `InboundMail`, the same class IMAP polling uses. *Append To*, auto-replies, attachments, notifications and reply threading behave as they do for a normal mailbox.

The relay Worker is a separate project. This document covers only the Frappe side. To stand up the relay and add your site as a tenant, follow [Deploying cloudflare-email-relay](/kb/email/deploying-cloudflare-email-relay/).

## Requirements

Frappe 16. The app declares `frappe >=16.0.0,<17.0.0` and Python 3.12 or newer.

A Cloudflare account on the Workers Paid plan, with your domain onboarded for **Email Sending** and **Email Routing** enabled on the zone.

A Cloudflare API token with the **Email Sending: Edit** permission.

For inbound mail: a site reachable over https, with `host_name` set in its site config, and a tenant entry for the site on your relay.

## Install the app

From the bench directory (see [Bench Operations](/kb/frappe/bench-operations/) for day-to-day bench commands), fetch the app and install it on your site:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">get-app</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">https://github.com/Avunu/cloudflare_email_delivery</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--site</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">SITE_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">install-app</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">cloudflare_email_delivery</span>
```

The app adds custom fields to Email Domain, Email Account and Communication, and overrides the Email Domain and Email Account classes. The fields ship as customizations that sync on migrate, so if they do not appear after install, run `bench --site <SITE_NAME> migrate`.

## Configure outbound

### Create the Email Domain

Open **Email Domain** and create or edit the domain you send from.

Tick **Send via Cloudflare**. The SMTP and IMAP server fields stop being required.

Fill **Cloudflare Account ID** and **Cloudflare API Token**. Both are mandatory once the box is ticked.

Save. The app checks the token against Cloudflare and refuses to save if Cloudflare rejects it or reports it as not active.

Note

The token check calls Cloudflare's token verification endpoint. It confirms the token is active; the Email Sending permission and the domain onboarding are only exercised when a message is actually sent.

### Create the Email Account

Open **Email Account** and create the account.

Set the email address and link the Email Domain from the previous step.

Tick **Enable Outgoing**. You do not need a password or any SMTP settings; the app blanks the server fields and skips connection tests.

Save.

Send yourself a test message from any document, then open **Email Queue** and check that the entry reaches *Sent*. If it fails, the error is recorded on the queue entry.

### What gets sent

Each recipient of a queue entry becomes one API call. The request carries the `From` address, the recipient, `Reply-To`, the text and HTML bodies, and attachments. Attachments with a `Content-ID` are sent as inline images so `cid:` references keep working.

Cloudflare allows only some headers. The app passes through the threading headers (`In-Reply-To`, `References`), the documented `List-*` headers, `Precedence`, `Auto-Submitted` and anything starting with `X-`, and drops the rest. Cloudflare's [header reference](https://developers.cloudflare.com/email-service/reference/headers/) is the authority on the list.

Cloudflare also replaces the `Message-ID` on every message. Frappe keeps its own id in Email Queue and Communication, so the app appends that id to `References`. The inbound side uses it to thread replies, as described below.

### Retries and failures

A network error or a 5xx response is retried up to three attempts in total, with a 1 second then 2 second back-off.

A 429 response waits for `Retry-After` when Cloudflare sends it, otherwise 2 seconds then 4, capped at 10 seconds per wait.

A 401 or 403 is treated as fatal. The remaining recipients in the same batch fail immediately instead of retrying with a bad token.

Any other 4xx fails at once, because retrying a malformed or oversized request cannot help.

If Cloudflare reports a recipient as permanently bounced or suppressed in its immediate response, that recipient is flagged. When no recipient could be reached the queue entry fails; when some could, the app logs a warning and counts the send as successful.

## Configure inbound

### Enable incoming on the Email Account

On the same Email Account:

Tick **Enable Incoming**.

Choose **Append To** (ToDo, Issue, Lead and so on) and set the usual options: auto-reply, attachment limit, notifications.

Save.

There is no IMAP server for this account, and the scheduler's mail pull does nothing for it. On save, the app generates a webhook key and a webhook secret once and never rotates them on later saves.

### Set host_name first

The webhook URL is built from the site's `host_name`. The app requires https and refuses to save otherwise, except on a loopback address (`localhost`, `127.0.0.1`, `::1`) or when the site is in developer mode. Set it before you save the account:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--site</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">SITE_NAM</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">set-config</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">host_name</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">https://site1.example.com</span>
```

### Hand the credentials to the relay

After saving, the **Cloudflare Email Receiving** section shows the **Webhook URL**. The form has a **Cloudflare Webhook** group of buttons:

**Copy Webhook URL**, available to anyone who can open the form.

**Copy Webhook Secret**, for users with the System Manager role.

**Regenerate Webhook Secret**, for System Managers.

Give the URL and the secret to whoever manages your relay. They become the tenant's `inboundUrl` and `secret`, together with the domain or domains whose mail should reach this site.

Then, in the Cloudflare zone's **Email Routing**, route the addresses you want (or the catch-all) to the relay Worker.

Warning

The Webhook URL embeds the key, and the secret signs every delivery. Treat both as credentials. Do not paste them into tickets, chat or Git.

### Rotate the secret

**Regenerate Webhook Secret** changes the secret only. The URL and key stay the same, so you only update the tenant's secret on the relay. Until you do, deliveries signed with the old secret are rejected with 401 and park as `rejected` on the relay, where they can be retried in bulk.

## Test inbound

Send a message to an address that routes to the relay and confirm a Communication appears on the Email Account's *Append To* document type. If nothing arrives, check **Error Log** and **Unhandled Email** on the site, then the relay's own logs.

You can also exercise the endpoint directly, which is useful for separating site problems from relay problems. This script signs a small message the way the relay does and posts it. Run it from any machine, with the real secret and the webhook URL from the Email Account:

```
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">import</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> hmac, hashlib, time, urllib.request, urllib.error</span>

<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">URL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<WEBHOOK_URL>"</span>
<span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">SECRET</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"<WEBHOOK_SECRET>"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">body </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> (</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"From: jane@example.org</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"To: support@example.com</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Subject: Webhook test</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Message-ID: <webhook-test-1@example.org></span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Hello from a manual test.</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">)</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">ts </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">str</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">int</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(time.time()))</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">sig </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"v1="</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">+</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> hmac.new(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">SECRET</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.encode(), ts.encode() </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">+</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"."</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">+</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> body, hashlib.sha256).hexdigest()</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">request </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> urllib.request.Request(</span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">URL</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">data</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">body, </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">method</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"POST"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">, </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">headers</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">{</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"Content-Type"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"message/rfc822"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"X-Email-Relay-Timestamp"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: ts,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"X-Email-Relay-Signature"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: sig,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"X-Email-Relay-Envelope-To"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"support@example.com"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"X-Email-Relay-Envelope-From"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"jane@example.org"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">,</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">})</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">try</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">with</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> urllib.request.urlopen(request) </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">as</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> response:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">        </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">print</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(response.status, response.read().decode())</span>
<span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">except</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> urllib.error.HTTPError </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">as</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> error:</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">    </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">print</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(error.code, error.read().decode())</span>
```

Replace `support@example.com` with an address on the Email Account's domain, or the domain check returns 422. A successful call prints status 200 and a body with `"ok": true` and the new Communication name as `remote_ref`.

### The webhook contract

The endpoint is `POST /api/method/cloudflare_email_delivery.api.inbound?key=<KEY>` with the raw message as a `message/rfc822` body. It is a guest method: the signature is the only credential. The relay sends these headers:

| Header                                                     | Meaning                                                                                       |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `X-Email-Relay-Id`                                         | The relay's queue id. The app uses it to drop duplicate retries.                              |
| `X-Email-Relay-Tenant`                                     | The tenant slug the relay routed by. It is logged.                                            |
| `X-Email-Relay-Timestamp`                                  | Unix seconds. Requests more than 300 seconds from the server clock are rejected.              |
| `X-Email-Relay-Signature`                                  | `v1=` followed by the hex HMAC-SHA256 of `<timestamp>.` plus the body, keyed with the secret. |
| `X-Email-Relay-Envelope-From`, `X-Email-Relay-Envelope-To` | The SMTP envelope. Written into the message as `Return-Path` and `Delivered-To` when absent.  |

The status code tells the relay what to do next:

| Response | Meaning                                                                                                 | Relay behavior        |
| -------- | ------------------------------------------------------------------------------------------------------- | --------------------- |
| 200      | Processed. `remote_ref` is `null` when your own outgoing mail looped back and was deliberately ignored. | Delivered             |
| 401      | Missing or bad signature, or stale timestamp.                                                           | Parked as rejected    |
| 404      | Unknown key, or incoming disabled on the account.                                                       | Parked as rejected    |
| 422      | Recipient domain is not the account's, invalid envelope, or the reference document refused the message. | Parked as rejected    |
| 500      | Anything else. The error is written to Error Log and the message is stored as an Unhandled Email.       | Retried with back-off |

Replay protection is the 300 second window plus the relay id check. Frappe refuses a request body larger than the site's `max_file_size` config value (25 MiB when it is not set) with a 413, which the relay treats as a rejection.

## How replies thread

Frappe threads replies on `In-Reply-To` only. Because Cloudflare rewrites the `Message-ID` of outgoing mail, a reply's `In-Reply-To` points at an id Frappe never issued. The app handles that by checking `In-Reply-To` first, then `References` from newest to oldest, for an id it recognises: one containing the site name, or one stored on a Communication or Email Queue entry. The first match becomes the reply target, so the reply lands on the right queue entry, Communication and document.

This relies on the replying mail client copying `References`, which mainstream clients do.

## Limits and known gaps

**Message size.** 5 MiB per outgoing message once encoded.

**Recipients.** 50 per message, To, Cc and Bcc combined. Frappe already sends one message per recipient, so this rarely matters.

**Custom headers.** At most 20 (Cloudflare counts only allow-listed headers toward this, but the app counts every header it sends, `X-` headers included), 2,048 bytes per value and 16 KB in total. The app trims the oldest `References` entries first if it must, and fails the send only when that is not enough.

**Dropped headers.** Headers outside Cloudflare's allow-list, such as `Disposition-Notification-To`, are not sent.

**Asynchronous bounces never reach Frappe.** The return path belongs to Cloudflare, so only recipients Cloudflare rejects in its immediate response are reported. Watch bounce activity in Cloudflare.

**Bcc.** Bcc recipients receive their copy, but the delivered message does not list them.

## Troubleshoot

These are the Frappe-side checks. For relay-side symptoms and the ops API, see [Troubleshooting Cloudflare Email](/kb/email/troubleshooting-cloudflare-email/).

| Symptom                                            | Where to look                                                                                               |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Domain will not save                               | The token failed verification. The error message includes Cloudflare's reason.                              |
| Account will not save, mentions https              | Set `host_name` in the site config to the public https address, then save again.                            |
| Queue entry failed with a Cloudflare error         | Read the error on the Email Queue entry. A 401 or 403 means the token or its permissions.                   |
| Mail sent but replies create new documents         | The replying client dropped `References`, or the original id is not in Email Queue or Communication.        |
| Inbound deliveries parked as rejected on the relay | The status code in the contract table above. 401 after a rotation means the relay still has the old secret. |
| Inbound returns 500                                | Open **Error Log** on the site and the matching **Unhandled Email** entry.                                  |

## Run the tests

The app ships a test suite. From the bench directory:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--site</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">TEST_SIT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">install-app</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">cloudflare_email_delivery</span>
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">bench</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--site</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E"><</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">TEST_SIT</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">E</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">></span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">run-tests</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--app</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">cloudflare_email_delivery</span>
```

The signing and API client tests are plain `unittest` and need no site:

```
<span style="--shiki-dark:#FFA657;--shiki-light:#953800">python</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-m</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">unittest</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">cloudflare_email_delivery.tests.test_relay</span>
```

If your development bench has a mail guard that strips email overrides, disable it for the test process, because it removes the very hooks these tests exercise.

## Related documents

[Email Without SMTP for Business Systems](/kb/email/email-without-smtp-for-business-systems/): the architecture and its limits.

[Deploying cloudflare-email-relay](/kb/email/deploying-cloudflare-email-relay/): the inbound Worker, tenants and secrets.

[Cloudflare Email for Odoo](/kb/email/cloudflare-email-for-odoo/): the same suite for Odoo 18.

[Troubleshooting Cloudflare Email](/kb/email/troubleshooting-cloudflare-email/): symptom-first checks across all three platforms.

Sources

- [github.com/Avunu/cloudflare_email_delivery](https://github.com/Avunu/cloudflare_email_delivery)
- [github.com/Avunu/cloudflare-email-relay](https://github.com/Avunu/cloudflare-email-relay)
- [developers.cloudflare.com/email-service/reference/headers](https://developers.cloudflare.com/email-service/reference/headers/)

Need help with business email?

Our notes can take you a long way, but sometimes you'd rather have someone who's done it before.

[Managed infrastructure](/services/infrastructure/)

[← PreviousEmail without SMTP for business systems](/kb/email/email-without-smtp-for-business-systems/)[Next →Send and receive Odoo email through Cloudflare](/kb/email/cloudflare-email-for-odoo/)

CC0This article is in the public domain ([CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/)), code samples included. Use it however helps you.

On this page

- [How it works](#how-it-works)
- [Requirements](#requirements)
- [Install the app](#install-the-app)
- [Configure outbound](#configure-outbound)
- [Create the Email Domain](#create-the-email-domain)
- [Create the Email Account](#create-the-email-account)
- [What gets sent](#what-gets-sent)
- [Retries and failures](#retries-and-failures)
- [Configure inbound](#configure-inbound)
- [Enable incoming on the Email Account](#enable-incoming-on-the-email-account)
- [Set host_name first](#set-host_name-first)
- [Hand the credentials to the relay](#hand-the-credentials-to-the-relay)
- [Rotate the secret](#rotate-the-secret)
- [Test inbound](#test-inbound)
- [The webhook contract](#the-webhook-contract)
- [How replies thread](#how-replies-thread)
- [Limits and known gaps](#limits-and-known-gaps)
- [Troubleshoot](#troubleshoot)
- [Run the tests](#run-the-tests)
- [Related documents](#related-documents)

[Back to top↑](#top)

Services

- [ERP implementation](/services/erp/)
- [Odoo](/services/erp/odoo/)
- [ERPNext](/services/erp/erpnext/)
- [Custom software](/services/custom-software/)
- [Devices & IoT](/services/devices-iot/)
- [Websites](/services/websites/)
- [Infrastructure](/services/infrastructure/)

Resources

- [Our work](/work/)
- [Open source](/open-source/)
- [Knowledge base](/kb/)
- [Insights](/insights/)

Company

- [About](/about/)
- [Team](/about/team/)
- [Partners](/partners/)
- [Contact](/contact/)

Clients

- [Project portal](https://erp.avunu.net/projects)
- [Invoices](https://erp.avunu.net/)
- [Support](https://erp.avunu.net/)

[![Avunu](/brand/avunu-logo-light.svg)](/)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M20.400 20.500h-3.600v-5.600c0-1.300 0-3-1.800-3s-2.100 1.400-2.100 2.900v5.700H9.400V9h3.400v1.600c.5-.9 1.600-1.900 3.400-1.900 3.600 0 4.300 2.400 4.300 5.500v6.300zM5.300 7.400a2.100 2.100 0 1 1 0-4.100 2.100 2.100 0 0 1 0 4.100zm1.800 13.100H3.600V9h3.500v11.500zM22.200 0H1.800C.8 0 0 .8 0 1.700v20.600c0 .9.800 1.700 1.800 1.700h20.400c1 0 1.800-.8 1.800-1.700V1.700C24 .8 23.200 0 22.200 0z">\</path>\</svg>\</av-icon>](https://www.linkedin.com/company/avunu)[\<av-icon data-jx-static>\<svg viewBox="0 0 24 24" width="20" height="20" fill="currentColor" stroke="none" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">\<path d="M12 .3a12 12 0 0 0-3.8 23.4c.6.1.8-.3.8-.6v-2c-3.3.7-4-1.6-4-1.6-.6-1.4-1.4-1.8-1.4-1.8-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.8 1.3 3.5 1 .1-.8.4-1.3.7-1.6-2.7-.3-5.5-1.3-5.5-5.9 0-1.3.5-2.4 1.2-3.2-.1-.3-.5-1.5.1-3.2 0 0 1-.3 3.3 1.2a11.500 11.500 0 0 1 6 0c2.300-1.500 3.300-1.200 3.300-1.200.6 1.700.2 2.900.1 3.200.8.8 1.200 1.900 1.200 3.200 0 4.600-2.800 5.600-5.500 5.900.4.400.8 1.100.8 2.200v3.300c0 .3.2.7.8.6A12 12 0 0 0 12 .3">\</path>\</svg>\</av-icon>](https://github.com/Avunu)[Client portal](https://erp.avunu.net/projects)[Start a project](/start/)

Avunu LLC · 948 East Philadelphia Street, York, PA 17403 · (717) 814-8540Knowledge base articles are in the public domain[Privacy](/privacy/)[Terms](/terms/)
