From 25a07070da3bfc1558de1a7864144822006e8cb2 Mon Sep 17 00:00:00 2001 From: Diogo Santos Date: Fri, 16 Oct 2026 14:14:19 +0100 Subject: [PATCH] [Email Service] Document sending reputation status and paused accounts --- .../api/send-emails/rest-api.mdx | 1 + .../api/send-emails/workers-api.mdx | 1 + .../email-service/concepts/deliverability.mdx | 45 +++++++++++++++++++ 3 files changed, 47 insertions(+) diff --git a/src/content/docs/email-service/api/send-emails/rest-api.mdx b/src/content/docs/email-service/api/send-emails/rest-api.mdx index c9426b7056d..f08ac9a1d10 100644 --- a/src/content/docs/email-service/api/send-emails/rest-api.mdx +++ b/src/content/docs/email-service/api/send-emails/rest-api.mdx @@ -142,6 +142,7 @@ The REST API returns the following error codes: | 403 | 10102 | `email.sending.error.authentication.forbidden` | Token lacks permission to send | | 403 | 10105 | `email.sending.error.authentication.not_entitled` | Account not entitled to use Email Sending | | 403 | 10203 | `email.sending.error.email.sending_disabled` | Sending disabled for this zone or account | +| 403 | 10207 | `email.sending.error.email.account_suspended` | Email Sending is paused for the account | | 404 | 10000 | `email.sending.error.not_found` | Resource not found | | 429 | 10004 | `email.sending.error.throttled` | Rate limit exceeded | | 500 | 10002 | `email.sending.error.internal_server` | Internal server error | diff --git a/src/content/docs/email-service/api/send-emails/workers-api.mdx b/src/content/docs/email-service/api/send-emails/workers-api.mdx index 6d8cff78f29..deb0d636e9b 100644 --- a/src/content/docs/email-service/api/send-emails/workers-api.mdx +++ b/src/content/docs/email-service/api/send-emails/workers-api.mdx @@ -191,6 +191,7 @@ The following error codes may be returned when sending emails: | `E_SENDER_NOT_VERIFIED` | Sender domain not verified | Attempting to send from unverified domain | | `E_RECIPIENT_NOT_ALLOWED` | Recipient not in allowed list | Recipient address not in `allowed_destination_addresses` | | `E_RECIPIENT_SUPPRESSED` | Suppressed recipient while dropping is off | At least one recipient is suppressed and **Drop suppressed recipients** is off | +| `E_ACCOUNT_SUSPENDED` | Email Sending is paused for the account | Account paused because of poor sending reputation | | `E_SENDER_DOMAIN_NOT_AVAILABLE` | Domain not available for sending | Domain not onboarded to Email Service | | `E_CONTENT_TOO_LARGE` | Email content exceeds size limit | Total message size exceeds the maximum | | `E_DELIVERY_FAILED` | Could not deliver the email | SMTP delivery failure, recipient server rejection | diff --git a/src/content/docs/email-service/concepts/deliverability.mdx b/src/content/docs/email-service/concepts/deliverability.mdx index edefb325208..a8612a969d3 100644 --- a/src/content/docs/email-service/concepts/deliverability.mdx +++ b/src/content/docs/email-service/concepts/deliverability.mdx @@ -71,6 +71,8 @@ Ensure that your deliverability stays above key metrics to avoid affecting your - Hard bounce rate < 2% - Complaint rate < 0.1% +Cloudflare also checks these metrics for your account. Refer to [Sending reputation status](#sending-reputation-status) for the thresholds and what happens when your account exceeds them. + #### Use separate domains for separate purposes Each domain builds its own deliverability reputation with inbox providers. Use separate domains or subdomains for different types of email so that one category does not affect the reputation of another. For example: @@ -80,3 +82,46 @@ Each domain builds its own deliverability reputation with inbox providers. Use s - `yourdomain.com` for important account-related communications This way, if marketing emails generate higher complaint rates, your transactional email deliverability is not impacted. Each domain can be onboarded separately through [domain configuration](/email-service/configuration/domains/). + +## Sending reputation status + +Cloudflare checks the sending reputation of each account daily. If your account sends too many messages that bounce, that receiving servers reject as spam, or that recipients report as spam, Cloudflare sends you a warning by email. If the problem continues, Cloudflare can pause Email Sending for your account. + +### Metrics and thresholds + +Cloudflare measures three metrics for each sending domain, over the last seven days: + +| Metric | How Cloudflare calculates it | Warning | At Risk | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------ | ------------ | +| Bounce rate | Messages that bounced because of the recipient (for example, the address or the domain does not exist), divided by all messages sent | 2% or more | 5% or more | +| Spam rejection rate | Messages that the receiving server rejected as spam, divided by all messages sent | 1% or more | 3% or more | +| Complaint rate | Messages that recipients reported as spam, divided by messages delivered | 0.1% or more | 0.2% or more | + +Your account status is the worst status of all your sending domains. One sending domain with poor metrics can change the status of the whole account. + +### Status levels + +| Status | Meaning | Can you send email? | +| ------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| Healthy | All metrics are below the Warning thresholds. | Yes | +| Warning | At least one metric is at or above its Warning threshold. | Yes | +| At Risk | At least one metric is at or above its At Risk threshold. A seven-day improvement period starts. | Yes | +| Paused | The account stayed At Risk for the full improvement period. After a review, Cloudflare paused Email Sending for the account. | No | + +Each time the status changes, Cloudflare sends an email to the users of the account. The [Cloudflare dashboard](https://dash.cloudflare.com/) also shows the current status on the account overview page. + +### If your account is paused + +While Email Sending is paused: + +- Cloudflare rejects every new message from the account. The [Workers binding](/email-service/api/send-emails/workers-api/) throws the error code `E_ACCOUNT_SUSPENDED`. The [REST API](/email-service/api/send-emails/rest-api/) returns HTTP `403` with error code `10207`. +- Cloudflare does not deliver messages that it accepted before the pause and that are still waiting for delivery. +- Cloudflare does not keep or queue the rejected messages. Your application must send them again after Cloudflare restores Email Sending. +- Your sending domains, DNS records, suppression list, and settings do not change. + +To restore Email Sending: + +1. Review the metrics for each sending domain in the dashboard. Find the metric that is At Risk. +2. Find the cause. Common causes are an old or purchased recipient list, a sign-up form that does not validate addresses, and messages that recipients did not expect. +3. Fix the cause. Remove invalid and inactive addresses from your list. Send only to recipients who asked for your email, and make it easy to unsubscribe. +4. [Contact Cloudflare Support](/support/contacting-cloudflare-support/) and ask Cloudflare to restore Email Sending. Tell Support what caused the problem and what you changed.