[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 Odoo 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 Odoo email through Cloudflare

Install the mail_cloudflare module to send Odoo mail through the Cloudflare Email Sending API and receive it by signed webhook, with no SMTP or IMAP server.

UpdatedNov 7, 2026

Applies toOdoo 18.0mail_cloudflare 18.0.1.2.0

Tagsemailcloudflareodoofetchmail

Reading time12 min

On this page[How it works](#how-it-works)[Before you start](#before-you-start)[Prepare Cloudflare](#prepare-cloudflare)[Email Sending](#email-sending)[Email Routing](#email-routing)[Install the module](#install-the-module)[Configure the outgoing mail server](#configure-the-outgoing-mail-server)[What Odoo sends](#what-odoo-sends)[Configure the incoming mail server](#configure-the-incoming-mail-server)[Rotate the secret](#rotate-the-secret)[The webhook contract](#the-webhook-contract)[Test it](#test-it)[Outbound](#outbound)[Inbound](#inbound)[Troubleshooting](#troubleshooting)[Test Connection fails](#test-connection-fails)[Mail goes to Exception](#mail-goes-to-exception)[Replies do not thread](#replies-do-not-thread)[Bounce messages never reach Odoo](#bounce-messages-never-reach-odoo)[Webhook errors](#webhook-errors)[Limitations](#limitations)[Related documents](#related-documents)

This document covers the `mail_cloudflare` Odoo module: how to install it, configure an outgoing mail server for Cloudflare Email Sending, create an incoming mail server that receives mail through a signed webhook, and test and troubleshoot both directions. Use it when you want Odoo to send and receive mail without running an SMTP relay or polling an IMAP mailbox. 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 module plugs into two stock Odoo models and leaves the rest of the mail stack alone.

**Outbound.** An outgoing mail server (`ir.mail_server`) gets a new authentication type, *Cloudflare Email Sending*. Instead of a host and a password it holds a Cloudflare account ID and an API token. When Odoo sends, the message it already built is turned into one REST call per recipient. The mail queue, failure handling and the `From` rewrite are still stock Odoo.

**Inbound.** An incoming mail server (`fetchmail.server`) gets a new type, *Cloudflare Email Worker*. It has no host or login. It carries a webhook key (part of the URL) and a signing secret, both generated when you save the record. A Cloudflare Worker, the [Cloudflare email relay](https://github.com/Avunu/cloudflare-email-relay), receives mail from Cloudflare Email Routing and POSTs the raw message to Odoo. Odoo verifies the signature and hands the message to the same `message_process()` path that IMAP polling uses, so aliases, reply threading and the server's fallback model behave as they always have.

Nothing is polled. The standard fetchmail cron stays off unless you also have an IMAP or POP server configured.

## Before you start

You need:

Odoo 18.0 with the `mail` module. The module's manifest version is `18.0.1.2.0` and it depends only on `mail`.

A Cloudflare account with your domain on it.

Workers Paid plan on the account, which Email Sending requires.

A public `https://` address for Odoo, set as the `web.base.url` system parameter.

Shell access to put the module in your Odoo addons path.

## Prepare Cloudflare

### Email Sending

In the Cloudflare dashboard, go to *Compute > Email Service > Email Sending* and choose *Onboard Domain* for every domain you send from. Cloudflare adds the bounce MX, SPF, DKIM and DMARC records for you.

Create an API token with the **Email Sending: Edit** permission.

Note your Cloudflare account ID. In the dashboard, open any domain's *Overview* page and find it under *API*, or press `Ctrl+K` (`Cmd+K` on macOS), search for "Copy account ID" and select the result.

### Email Routing

Enable Email Routing on the zone for free. Then route the addresses Odoo should receive, or the catch-all, to the deployed relay Worker with the *Send to a Worker* action. [Deploying cloudflare-email-relay](/kb/email/deploying-cloudflare-email-relay/) covers deploying the Worker and adding Odoo as a tenant. The [relay repository](https://github.com/Avunu/cloudflare-email-relay) holds the code.

## Install the module

Clone the [mail-addons](https://github.com/Avunu/mail-addons) repository on its `18.0` branch and add it to your Odoo `addons_path` (in an [odoo-nix](https://github.com/Avunu/odoo-nix) project, `odoo module add Avunu/mail-addons 18.0` does both). Then, in Odoo with developer mode on, open *Apps*, choose *Update Apps List*, search for "Cloudflare Email Transport" and install it.

Warning

Uninstalling the module resets Cloudflare-typed outgoing servers to the default type with no host. Archive them first.

## Configure the outgoing mail server

With developer mode on, go to *Settings > Technical > Email > Outgoing Mail Servers* and create a new record.

| Field                                        | Value                                   |
| -------------------------------------------- | --------------------------------------- |
| Authenticate with                            | Cloudflare Email Sending                |
| Cloudflare Account ID                        | `<CLOUDFLARE_ACCOUNT_ID>`               |
| Cloudflare API Token                         | `<CLOUDFLARE_API_TOKEN>`                |
| FROM Filtering                               | `example.com`, the domain you onboarded |
| Convert attachments to links for emails over | 5 MB, set automatically                 |

Choosing the Cloudflare authentication blanks the SMTP host and port and hides the Connection tab, since none of it applies.

The module enforces three things when you save: an account ID, an API token and a FROM Filtering value are all required. The filter matters because Cloudflare only sends from onboarded domains. With the filter set, Odoo rewrites a `From` address outside your domain to the notifications address instead of sending something Cloudflare will refuse.

Click *Test Connection*. For Cloudflare servers this calls the token verification endpoint and succeeds when the token is active. It does not send a message. *Detect Max Limit* sets the size to 5 MB, which is Cloudflare's fixed limit rather than a measured value.

Also check *Settings > General > Discuss > Alias Domain*. It should be the domain you routed in Cloudflare, so `catchall@`, `bounce@` and `notifications@` exist on it.

### What Odoo sends

Each message becomes one JSON request to the Cloudflare send API, carrying these pieces:

`From`, `To` and `Cc` from the headers, and `Bcc` from the envelope.

Text and HTML bodies, and `Reply-To`.

Attachments, with inline ones tied to their `Content-ID`.

Only the headers Cloudflare allows: threading headers, `List-*`, `Precedence`, `Auto-Submitted`, anything starting with `X-`, and a few others. Unknown headers are dropped rather than sent, because one disallowed header fails the whole request.

Cloudflare replaces the `Message-ID` of every message. To keep reply threading working, the module appends Odoo's own message ID to `References`. Mail clients copy `References` into replies, and Odoo matches on it.

Retries are short. Network errors and 5xx responses are retried with a 1 second and then 2 second back-off, up to 3 attempts. A 429 honors `Retry-After`, capped at 10 seconds. A 401 or 403 is treated as fatal and the rest of the batch fails immediately. Other 4xx responses are not retried.

## Configure the incoming mail server

Go to *Settings > Technical > Email > Incoming Mail Servers* and create a new record.

Set the type to **Cloudflare Email Worker**. Optionally set *Create a New Record* to a fallback model, which receives mail that no alias matches.

Save the record. The webhook key and secret are generated on save, and the form shows a *Webhook URL*, *Webhook Key* and *Webhook Secret* with copy buttons.

Click *Test & Confirm*.

Give the Webhook URL and Webhook Secret to your relay Worker as this tenant's `inboundUrl` and `secret`.

The URL is built from `web.base.url`. Confirmation fails unless that parameter is an `https://` address. Plain `http://` is accepted only for `localhost`, `127.0.0.1` or `::1`, which exists for local `wrangler dev` work. Set the parameter to your public HTTPS address and freeze it with `web.base.url.freeze`, so Odoo does not rewrite it from the browser's address.

### Rotate the secret

Use *Regenerate Secret* on the server form to revoke a leaked or retired secret. It changes only the secret. The key, and so the URL, stay the same, so you only update the secret in the relay. Requests signed with the old secret are rejected as soon as you regenerate.

A duplicated server gets its own key and secret rather than copying the original's.

## The webhook contract

The relay sends `POST /mail_cloudflare/inbound/<KEY>` with a `message/rfc822` body containing the raw message. These headers accompany it.

| Header                        | Meaning                                                                                       |
| ----------------------------- | --------------------------------------------------------------------------------------------- |
| `X-Email-Relay-Id`            | The relay's queue ID, logged and echoed back.                                                 |
| `X-Email-Relay-Tenant`        | The tenant the relay routed by, logged.                                                       |
| `X-Email-Relay-Timestamp`     | Unix seconds. Rejected when more than 300 seconds from Odoo's clock.                          |
| `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` | The SMTP envelope sender. Written into the message as `Return-Path` when absent.              |
| `X-Email-Relay-Envelope-To`   | The routed address. Written into the message as `Delivered-To` when absent.                   |

The envelope headers matter. Odoo recognizes aliases and Bcc'd recipients from `Delivered-To`, and bounces from `Return-Path`.

Odoo answers in JSON, and the status code tells the relay what to do next.

| Response | Meaning                                                                                                          | Relay action          |
| -------- | ---------------------------------------------------------------------------------------------------------------- | --------------------- |
| `200`    | Processed. `remote_ref` is the record ID, or `null` for a duplicate, bounce or loop that was ignored on purpose. | Delivered             |
| `401`    | Bad or missing signature, or stale timestamp.                                                                    | Parked as rejected    |
| `404`    | Unknown key, or the server is not confirmed or is archived.                                                      | Parked as rejected    |
| `422`    | No route: no alias matched and there is no fallback model.                                                       | Parked as rejected    |
| `500`    | Anything else.                                                                                                   | Retried with back-off |

The route needs no session. The signature is the credential, and a failed check never says which part failed. Duplicates are ignored by `Message-Id`, so a retried push is harmless. Messages without a `Message-Id` cannot be deduplicated.

Note

On a host that serves several databases, set `dbfilter` or `db_name` so Odoo can pick the database from the request. A `?db=` redirect would drop the POST body.

## Test it

### Outbound

Click *Test Connection* on the outgoing server and confirm it succeeds.

Send a real message from Odoo, for example a chatter message to a partner whose address is on your side, and check it arrives.

If it does not, open the failed outgoing mail record. A mail that Cloudflare refused ends in the *Exception* state with the reason in its failure text, prefixed with `CloudflareEmailError`.

### Inbound

Send mail to an address you routed to the relay Worker and watch for a new record or a chatter reply. If you want to test Odoo in isolation, sign a request yourself. This Python sketch follows the contract above, and is not a shipped tool.

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

<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">url </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">"https://odoo.example.com/mail_cloudflare/inbound/<WEBHOOK_KEY>"</span>
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">secret </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:#FF7B72;--shiki-light:#CF222E">b</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"From: jane@example.com</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</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">Subject: Webhook test</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">Message-Id: <webhook-test-1@example.com></span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">\r\n\r\n</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">Hello.</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">timestamp </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">digest </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> hmac.new(secret.encode(), </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">f</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">{</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">timestamp</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">}</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">."</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">.encode() </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(url, </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-Id"</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">: </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"manual-test"</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">: timestamp,</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">: </span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">f</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">"v1=</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">{</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">digest</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">}</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">    </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.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-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:#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:#79C0FF;--shiki-light:#0550AE">print</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">(urllib.request.urlopen(request).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>
```

A routed message answers with a `200` and an `ok` flag. If no alias matches `support@example.com` and the server has no fallback model, you get a `422`, which is the correct result. Sending the same `Message-Id` twice returns `200` with a `null``remote_ref` the second time.

The module's own test suite never contacts Cloudflare. It scripts the API responses and signs real HTTP requests against a running test server. To run it from an odoo-nix dev shell, turn the dev mail catcher off first. It is server-wide and would swallow every send the tests make:

```
<span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328">ODOO_MAILCATCH_ENABLED</span><span style="--shiki-dark:#FF7B72;--shiki-light:#CF222E">=</span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">0</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#FFA657;--shiki-light:#953800">python</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">odoo/odoo-bin</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-c</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">odoo.conf</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-d</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">mc_test</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">-i</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">mail_cloudflare</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--test-enable</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--test-tags</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#A5D6FF;--shiki-light:#0A3069">/mail_cloudflare</span><span style="--shiki-dark:#E6EDF3;--shiki-light:#1F2328"> </span><span style="--shiki-dark:#79C0FF;--shiki-light:#0550AE">--stop-after-init</span>
```

## Troubleshooting

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

### Test Connection fails

The message includes Cloudflare's response. A 401 or 403 means the token is wrong or lacks permission. An inactive token is reported as such. "Could not reach Cloudflare" is a network problem between Odoo and `api.cloudflare.com`.

### Mail goes to Exception

Read the failure reason on the mail. The common ones:

**No recipient could be reached.** Cloudflare synchronously bounced or suppressed every recipient. If only some were refused, Odoo logs a warning and reports success.

**More than 50 recipients.** To, Cc and Bcc combined are capped at 50.

**Message is too large.** The encoded message must fit in 5 MiB, and Odoo checks before it makes a request. Attachments attached to a record are turned into links above the size limit. Attachments added in the composer are always embedded.

**Header limits.** Cloudflare allows 20 allow-listed custom headers, 16 KB of headers in total and 2,048 bytes per value. The module counts every header it sends against the 20, `X-` headers included. Odoo trims the oldest `References` entries first.

**Refused `From` address.** A mail forced onto the Cloudflare server whose `From` is not on the onboarded domain is sent unchanged and refused. Odoo only rewrites `From` when it picks the server through FROM Filtering.

**No body.** Cloudflare needs at least one non-empty text or HTML body.

### Replies do not thread

Threading depends on the replying mail client keeping `References`, which mainstream clients do. If one strips it, the reply creates a new record instead.

### Bounce messages never reach Odoo

Asynchronous bounces go to a Cloudflare-controlled address, not Odoo's `bounce@` alias. Only the synchronous failures described above are visible to Odoo.

### Webhook errors

Check the Odoo log first. Every rejection is logged with the relay ID from `X-Email-Relay-Id`.

| Symptom                          | Likely cause                                                                                                                               |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| 401                              | The relay holds an old secret (after *Regenerate Secret*), the body was altered in transit, or the clocks differ by more than 300 seconds. |
| 404                              | The key in the URL is wrong, the server is archived, or you did not click *Test & Confirm*.                                                |
| 422                              | No alias matches the routed address and the server has no fallback model. Set one or create the alias.                                     |
| 500                              | An unexpected error in Odoo. The relay retries with back-off. Read the traceback in the Odoo log.                                          |
| Confirmation refuses to proceed  | `web.base.url` is not `https://`. Fix it and confirm again.                                                                                |
| Nothing arrives and no log lines | The request never reached Odoo. Check Email Routing, the relay's tenant secret and your reverse proxy.                                     |

## Limitations

Cloudflare rewrites `Message-ID`, so Odoo's own ID survives only inside `References`.

Asynchronous bounces never reach `bounce@`.

The 5 MiB message limit is Cloudflare's.

A stock SMTP server pointed at `smtp.mx.cloudflare.net` on port 465 (SSL/TLS, user `api_token`, password the token) is a sending-only alternative that needs no module. It gives no per-recipient result, and it has not been verified whether `Message-ID` survives it.

## 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 Frappe and ERPNext](/kb/email/cloudflare-email-for-frappe-and-erpnext/): the same suite for Frappe 16.

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

Sources

- [github.com/Avunu/mail-addons](https://github.com/Avunu/mail-addons)
- [github.com/Avunu/cloudflare-email-relay](https://github.com/Avunu/cloudflare-email-relay)
- [developers.cloudflare.com/email-service](https://developers.cloudflare.com/email-service/)

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/)

[← PreviousSend and receive Frappe and ERPNext email through Cloudflare](/kb/email/cloudflare-email-for-frappe-and-erpnext/)[Next →Send WordPress email through Cloudflare Email Sending](/kb/email/cloudflare-email-for-wordpress/)

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)
- [Before you start](#before-you-start)
- [Prepare Cloudflare](#prepare-cloudflare)
- [Email Sending](#email-sending)
- [Email Routing](#email-routing)
- [Install the module](#install-the-module)
- [Configure the outgoing mail server](#configure-the-outgoing-mail-server)
- [What Odoo sends](#what-odoo-sends)
- [Configure the incoming mail server](#configure-the-incoming-mail-server)
- [Rotate the secret](#rotate-the-secret)
- [The webhook contract](#the-webhook-contract)
- [Test it](#test-it)
- [Outbound](#outbound)
- [Inbound](#inbound)
- [Troubleshooting](#troubleshooting)
- [Test Connection fails](#test-connection-fails)
- [Mail goes to Exception](#mail-goes-to-exception)
- [Replies do not thread](#replies-do-not-thread)
- [Bounce messages never reach Odoo](#bounce-messages-never-reach-odoo)
- [Webhook errors](#webhook-errors)
- [Limitations](#limitations)
- [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/)
