diff --git a/src/content/docs/email-service/api/send-emails/smtp.mdx b/src/content/docs/email-service/api/send-emails/smtp.mdx index 4abb8db9fef..82a13dad8bb 100644 --- a/src/content/docs/email-service/api/send-emails/smtp.mdx +++ b/src/content/docs/email-service/api/send-emails/smtp.mdx @@ -94,7 +94,9 @@ Thanks for signing up. 221 mx.cloudflare.net Cloudflare Email ESMTP Service closing transmission channel ``` -The `250 2.0.0 Ok` response after the message body includes the assigned Message-ID. Use it to correlate the submission with delivery logs in the dashboard. +A `250 2.0.0 Ok` response after the message body normally includes the assigned Message-ID. Use it to correlate the submission with delivery logs in the dashboard. + +When **Drop suppressed recipients** is on and all recipients are suppressed, SMTP may return `250 2.0.0 Ok` without a Message-ID and deliver nothing. Refer to [Suppressed recipients](#suppressed-recipients). ## Examples @@ -134,6 +136,20 @@ Cloudflare's SMTP server returns standard [RFC 5321](https://datatracker.ietf.or | `552 5.3.4` | Message exceeds the 5 MiB `SIZE` limit. | | `554` | Transaction failed — content rejected by policy. | +## Suppressed recipients + +SMTP accepts a syntactically valid recipient with `250 2.1.5 Ok` during `RCPT TO`. Email Service checks the [suppression list](/email-service/concepts/suppressions/) for the account after receiving the message body. + +Behavior depends on the per-sending-domain [**Drop suppressed recipients** setting](/email-service/configuration/domains/#drop-suppressed-recipients). The setting is off by default. + +When the setting is off, any suppressed recipient causes SMTP to reject the entire message. When the setting is on, Email Service removes suppressed recipients and continues processing the remaining recipients. + +If all recipients are suppressed while dropping is on, SMTP may return `250 2.0.0 Ok` without a Message-ID. It delivers nothing in this case. + +Use [Email sending logs](/email-service/observability/logs/) to confirm delivery. Suppressed recipients appear with a **Rejected** result. + +Suppression produces a `message.rejected` event in [Email Sending event subscriptions](/email-service/platform/event-subscriptions/) with `rejection.reason` set to `suppressed`. + ## Troubleshooting ### `535 5.7.8 Authentication failed` 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 f4803ae866c..75c8a94c4db 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 @@ -190,7 +190,7 @@ The following error codes may be returned when sending emails: | `E_TOO_MANY_ATTACHMENTS` | Too many attachments in `attachments` array | `attachments` array exceeds 32 entries | | `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` | Recipient is on suppression list | Email address has bounced or reported your emails as spam | +| `E_RECIPIENT_SUPPRESSED` | Suppressed recipient while dropping is off | At least one recipient is suppressed and **Drop suppressed recipients** is off | | `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 | @@ -205,6 +205,8 @@ The following error codes may be returned when sending emails: | `E_HEADERS_TOO_LARGE` | Headers payload too large | Total custom headers exceed 16 KB limit | | `E_HEADERS_TOO_MANY` | Too many headers | More than 20 allowlisted (non-X) custom headers | +**Drop suppressed recipients** is off by default. When you [turn on the setting](/email-service/configuration/domains/#drop-suppressed-recipients), Email Service removes suppressed recipients and processes the remaining recipients. + ## Legacy `EmailMessage` API The `EmailMessage` API remains supported for backward compatibility. Use it when you already have a raw [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322) MIME message to send. For new code, prefer the structured [`send()` method](#send-method) above. diff --git a/src/content/docs/email-service/concepts/deliverability.mdx b/src/content/docs/email-service/concepts/deliverability.mdx index 2f5ded0d459..edefb325208 100644 --- a/src/content/docs/email-service/concepts/deliverability.mdx +++ b/src/content/docs/email-service/concepts/deliverability.mdx @@ -21,14 +21,15 @@ Bounces occur when emails cannot be delivered to recipients. There are two types Hard bounces are permanent delivery failures that occur when: -- Email address doesn't exist (`user@domain.com` → No such user) -- Domain does not exist (`user@nonexistentdomain.com`) -- Recipient server permanently blocks your domain -- Content rejected as spam by recipient filters +- The recipient address does not exist. +- The recipient domain does not exist. +- The receiving server permanently rejects the recipient. **Hard bounces are never retried** because the failure is permanent. Emails that hard bounce will generate a bounce notification to the sender address and can be monitored through [analytics](/email-service/observability/metrics-analytics/). -Hard bounced addresses are automatically added to your [suppression list](/email-service/concepts/suppressions/) to protect your sender reputation. +Email Service adds eligible recipient-side hard bounces to your [suppression list](/email-service/concepts/suppressions/). Suppressions have no expiration when the mailbox or domain does not exist. + +They also have no expiration when the recipient remains unavailable across repeated delivery attempts. Other eligible hard-bounce suppressions last seven days. ### Soft bounces @@ -38,7 +39,7 @@ Soft bounces are temporary failures that may succeed if retried: - Email server temporarily down - Rate limiting or greylisting -Cloudflare automatically retries soft bounces with exponential backoff over an extended period. +Cloudflare automatically retries soft bounces with exponential backoff. Eligible recipient-side failures create a 24-hour suppression. ## Reputation management diff --git a/src/content/docs/email-service/concepts/email-lifecycle.mdx b/src/content/docs/email-service/concepts/email-lifecycle.mdx index 9478a52293d..7ad9bceeb32 100644 --- a/src/content/docs/email-service/concepts/email-lifecycle.mdx +++ b/src/content/docs/email-service/concepts/email-lifecycle.mdx @@ -32,9 +32,7 @@ flowchart LR ### Stage details 1. **Request received:** The system validates the email format, sender authorization, and message structure. Invalid requests are rejected immediately and do not proceed to the next stage. - 2. **Rate limit check:** The system checks sending [limits](/email-service/platform/limits/) per account, domain, and recipient to prevent abuse. Requests that exceed these limits are temporarily rejected and must be retried later. - 3. **Authentication and reputation**: The system performs email authentication checks and evaluates sender reputation: - **SPF (Sender Policy Framework)**: Verifies that the sending IP address is authorized to send emails for the domain by checking DNS TXT records. This prevents domain spoofing and improves deliverability. - **DKIM (DomainKeys Identified Mail)**: Validates the email's cryptographic signature to ensure message integrity and authenticate the sender domain. This builds trust with recipient servers. @@ -42,17 +40,19 @@ flowchart LR These authentication mechanisms work together to establish sender legitimacy and protect against email fraud. Senders with low reputation scores may experience throttling or delayed processing. -4. **Suppression list check:** The system checks the recipient against your account's suppression list, which includes bounces, complaints, and unsubscribes. Recipients found on this list are blocked from receiving the email. +4. **Suppression list check:** The system checks each recipient against the Email Sending [suppression list](/email-service/concepts/suppressions/) for your account. Suppressed recipients do not reach the delivery stage or count toward your quota. + + The per-sending-domain [**Drop suppressed recipients** setting](/email-service/configuration/domains/#drop-suppressed-recipients) is off by default. When off, the REST API returns `400`, the Workers binding throws `E_RECIPIENT_SUPPRESSED`, and SMTP rejects the message if any recipient is suppressed. + + When on, Email Service removes suppressed recipients and processes the remaining recipients. Email Service does not process unsubscribe links, so add unsubscribed recipients manually. 5. **Delivery attempt:** The system connects to the recipient's mail server and attempts message delivery via SMTP. When delivery fails, the system applies different retry logic based on the failure type: - **Soft bounces (4xx responses)**: The system retries delivery using exponential backoff timing - **Hard bounces (5xx responses)**: The system marks the email as permanently failed with no retry attempts - 6. **Server response handling:** The system processes SMTP response codes from the recipient server to determine the final email status: - **2xx codes**: The email was delivered successfully - **4xx codes**: Temporary failure occurred and the email will be retried - **5xx codes**: Permanent failure occurred and the email cannot be delivered - 7. **Final status and metrics:** Based on the server response, the system assigns emails one of these final statuses: - **Delivered**: The email was successfully accepted by the recipient server - **Delivery failed**: The email permanently failed delivery (hard bounce) or exceeded the maximum retry attempts (soft bounce). This status appears as `deliveryFailed` when querying the [GraphQL Analytics API](/email-service/observability/metrics-analytics/). @@ -82,18 +82,12 @@ flowchart LR ### Stage details 1. **SMTP receipt:** A sending server connects to a Cloudflare MX server and submits the message over SMTP. Messages larger than the [inbound message size limit](/email-service/platform/limits/) are rejected at this stage. - 2. **Authentication check:** The system performs [SPF, DKIM, DMARC, and ARC](/email-service/concepts/email-authentication/) checks on the incoming message. Mail that fails authentication according to the sender's DMARC policy is rejected. Mail from IP addresses on a Realtime Block List is also rejected at this stage. Refer to [Postmaster information](/email-service/reference/postmaster/) for details. - 3. **Rule match:** The system matches the recipient address against your configured [routing rules](/email-service/configuration/email-routing-addresses/). If [subaddressing](/email-service/configuration/email-routing-addresses/#subaddressing) is enabled, sub-addressed recipients fall back to the base routing rule. If no rule matches and the [catch-all rule](/email-service/configuration/email-routing-addresses/#catch-all-rule) is enabled, the catch-all rule applies. - 4. **Action:** The system applies the matched rule's action: - **Send to an email**: The message is forwarded to the verified destination address (stage 5). - **Send to a Worker**: The message is passed to your [Worker](/email-service/api/route-emails/email-handler/). The Worker can call `forward()`, `reply()`, or `setReject()`. - **Drop**: The message is silently discarded. No further processing occurs. - 5. **ARC sign and SRS rewrite:** For forwarded messages, the system adds an ARC seal preserving the original authentication results and rewrites the envelope sender using the [Sender Rewriting Scheme](/email-service/reference/postmaster/#sender-rewriting). This allows SPF to pass at the destination server. - 6. **Outbound delivery:** The system connects to the destination mail server and delivers the message. Soft bounces are retried with exponential backoff. Hard bounces are returned to the original sender in-session as upstream SMTP errors. Refer to [Postmaster: SMTP errors](/email-service/reference/postmaster/#smtp-errors). - 7. **Final status and metrics:** The final outcome is recorded and available through the [Activity log](/email-service/observability/logs/) and the [GraphQL Analytics API](/email-service/observability/metrics-analytics/). diff --git a/src/content/docs/email-service/concepts/suppressions.mdx b/src/content/docs/email-service/concepts/suppressions.mdx index 27cb7c2456a..f1f128dab39 100644 --- a/src/content/docs/email-service/concepts/suppressions.mdx +++ b/src/content/docs/email-service/concepts/suppressions.mdx @@ -1,36 +1,97 @@ --- title: Suppression lists -description: Manage Email Service suppression lists to prevent sending to invalid or complaining addresses. +description: Understand suppression scope, triggers, expiration, and enforcement. pcx_content_type: concept summary: | - Manage email suppression lists to prevent emails from being sent to addresses that shouldn't receive them, protecting your sender reputation with automatic and manual suppression management. + Suppression lists prevent Email Service from sending to recipients who should not receive mail. Cloudflare adds entries after eligible bounces and spam complaints. You can also add entries manually. sidebar: order: 4 products: - email-service --- -Suppression lists prevent emails from being sent to addresses that should not receive them, protecting your sender reputation and ensuring compliance with anti-spam regulations. +An Email Sending suppression list contains recipients that Email Service does not contact. Suppressions protect your sender reputation and help prevent sending unwanted mail. -## Account suppression list +Cloudflare creates suppressions after eligible delivery failures and spam complaints. You can also add entries for recipients who should not receive mail. -Cloudflare automatically manages suppressions for your account to preserve your reputation as an email sender. +To add or remove entries, refer to [Manage suppressions](/email-service/configuration/suppressions/). Suppressions only apply to Email Sending. -Cloudflare will automatically add email addresses to your account suppression list for the following reasons: +## Suppression scope -- **Hard bounces**: Invalid or non-existent email addresses are immediately suppressed. -- **Repeated soft bounces**: Addresses that repeatedly fail delivery are temporarily or permanently suppressed based on the frequency and pattern of failures. -- **Spam complaints**: Recipients who marked emails as spam. Cloudflare integrates with Postmasters to receive spam complaints and automatically updates your account suppression list to prevent you from sending emails to this email address and preserve your email sending reputation. +Suppressions are account-scoped. Once an email address is on the suppression list, Email Service suppresses sends to that address from every domain in your account. -You may also manually add or remove email addresses from your suppression list as needed. The removal of email addresses that have been automatically added to your suppression list as a result of a spam complaint is limited to avoid abuse. +If you need separate suppression lists for different use cases, consider using separate Cloudflare accounts. + +## Suppression rules + +The following table describes automatic and manual creation rules and expiration: + +| Reason | Created when | Expiration | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | +| Manual (`manual`) | You add the recipient through the dashboard or API | The time you choose, or no expiration | +| Spam complaint (`complaint`) | Cloudflare receives and validates a complaint from the recipient's email provider | No expiration | +| Hard bounce (`hard_bounce`) | Any other eligible recipient-side permanent rejection occurs | 7 days | +| Hard bounce (`hard_bounce`) | The recipient mailbox or domain does not exist, or a recipient-side issue persists across repeated delivery attempts | No expiration | +| Soft bounce (`soft_bounce`) | An eligible recipient-side temporary failure occurs, such as a full mailbox or rate limit | 24 hours by default | + +The [account Email Sending suppression management REST API](/api/resources/email_sending/subresources/suppressions/) can return Cloudflare-managed entries with a `policy` reason. Clients must use `read_only` to determine mutability, not infer it from `reason`. + +You cannot update or delete an entry when `read_only` is `true`. To investigate one, [contact Cloudflare Support](/support/contacting-cloudflare-support/). + +### Manual suppressions + +Manual suppressions allow you to add application-level decisions that Email Service cannot observe. For example, if a user manually unsubscribes from emails in your app, you can add their email to your Email Service suppression list. + +You select the expiration when creating the entry. An entry without an expiration remains active until you delete it. + +### Spam complaints + +Email providers send feedback reports when recipients mark messages as spam. Cloudflare validates these reports before creating complaint suppressions. + +Complaint suppressions are created without an expiration. You can change or delete one when `read_only` is `false`. + +We recommend changing or deleting one only after the recipient opts in again through your application. + +### Hard bounces + +A hard bounce is a permanent rejection of one delivery attempt. Some addresses become valid again after their owner fixes the mailbox or domain. + +Email Service creates a suppression without an expiration when the mailbox or domain does not exist. It also does this when a recipient-side issue persists across repeated delivery attempts without a successful delivery. + +Other eligible hard-bounce suppressions last seven days. + +### Soft bounces + +A soft bounce is a temporary recipient-side failure. Examples include a full mailbox, a temporarily unavailable server, or recipient-side rate limiting. + +Eligible soft-bounce suppressions last 24 hours by default. Email Service resumes sending after the suppression expires. + +Not every temporary delivery failure creates a suppression. For example, Email Service does not suppress a recipient for a sender-side authentication or reputation problem. + +## Enforcement by sending method + +Each sending domain has a [**Drop suppressed recipients** setting](/email-service/configuration/domains/#drop-suppressed-recipients). The setting is off by default. + +| Sending method | Setting off | Setting on | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [REST API](/email-service/api/send-emails/rest-api/) | Returns `400` and rejects the request when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. | +| [Workers binding](/email-service/api/send-emails/workers-api/) | Throws `E_RECIPIENT_SUPPRESSED` and rejects the `send()` call when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. | +| [SMTP](/email-service/api/send-emails/smtp/) | Rejects the message when any recipient is suppressed. | Removes suppressed recipients and processes the remaining recipients. If none remain, SMTP may return `250 2.0.0 Ok` without a Message-ID and delivers nothing. | + +Suppressed recipients do not count toward your [monthly quota](/email-service/platform/pricing/) or daily sending limits. They appear as **Rejected** in [Email sending logs](/email-service/observability/logs/). ## Best practices -### List hygiene +- Add manual suppressions for unsubscribes. +- Require recipients to opt in again through your application. +- Verify addresses before deleting suppressions. +- Investigate patterns across repeated bounces. +- Let temporary suppressions expire automatically. -Maintaining clean suppression lists is essential for optimal email delivery performance and sender reputation. Regular maintenance helps identify delivery issues early and ensures legitimate recipients can receive your emails. +## Related resources -- Review suppression lists monthly -- Remove temporary suppressions that have expired -- Identify patterns in suppressed addresses -- Update email validation rules based on common issues +- Use [Manage suppressions](/email-service/configuration/suppressions/) to manage entries through the dashboard or API. +- Review [Email deliverability](/email-service/concepts/deliverability/) to understand bounce and complaint effects. +- Follow [Email lifecycle](/email-service/concepts/email-lifecycle/) to locate suppression checks in the sending flow. +- Review [Suppression list limits](/email-service/platform/limits/#suppression-list-limits) for API limits. +- Use [Email sending logs](/email-service/observability/logs/) to investigate rejected sends. diff --git a/src/content/docs/email-service/configuration/domains.mdx b/src/content/docs/email-service/configuration/domains.mdx index f91f22bcff8..d9921890c9e 100644 --- a/src/content/docs/email-service/configuration/domains.mdx +++ b/src/content/docs/email-service/configuration/domains.mdx @@ -10,7 +10,7 @@ products: - email-service --- -import { DashButton, Render, Tabs, TabItem } from "~/components"; +import { DashButton, Render, Steps, Tabs, TabItem } from "~/components"; Configure your domains to work with Cloudflare Email Service. This includes DNS record management, domain verification, and advanced domain settings. @@ -327,6 +327,25 @@ Disabling Email Routing on a domain stops processing incoming emails and removes 2. DNS records are tied to the account, not to specific users. 3. Use Cloudflare account-level permissions to manage access. +## Drop suppressed recipients + +**Drop suppressed recipients** controls suppression handling for one sending domain. The setting is off by default. + +When the setting is off, a message containing any [suppressed recipient](/email-service/concepts/suppressions/) fails. The REST API returns `400`, the Workers binding throws `E_RECIPIENT_SUPPRESSED`, and SMTP rejects the message. + +When the setting is on, Email Service removes suppressed recipients and processes the remaining recipients. + +To turn on the setting: + + +1. In the Cloudflare dashboard, go to **Compute** > **Email Service** > **Email Sending**. + + + +2. Select the sending domain, then open **Settings**. +3. Turn on **Drop suppressed recipients**. + + ## Email preview Turn on **Email preview** to store sent messages so you can inspect their content in the [Activity log](/email-service/observability/logs/#message-preview). Previews cover messages sent while the setting is turned on and are retained for about seven days. diff --git a/src/content/docs/email-service/configuration/index.mdx b/src/content/docs/email-service/configuration/index.mdx index 4d1dd7f2b7a..75f6fc4a4f0 100644 --- a/src/content/docs/email-service/configuration/index.mdx +++ b/src/content/docs/email-service/configuration/index.mdx @@ -1,6 +1,6 @@ --- title: Configuration -description: Configure domains, routing rules, and MTA-STS for Cloudflare Email Service. +description: Configure domains, routing rules, suppressions, and MTA-STS for Cloudflare Email Service. pcx_content_type: navigation sidebar: order: 4 @@ -12,6 +12,6 @@ products: import { DirectoryListing } from "~/components"; -Configure domains, routing rules, subdomains, and MTA-STS for Cloudflare Email Service. +Configure domains, routing rules, subdomains, suppressions, and MTA-STS for Cloudflare Email Service. diff --git a/src/content/docs/email-service/configuration/suppressions.mdx b/src/content/docs/email-service/configuration/suppressions.mdx new file mode 100644 index 00000000000..645f9ef5804 --- /dev/null +++ b/src/content/docs/email-service/configuration/suppressions.mdx @@ -0,0 +1,71 @@ +--- +title: Manage suppressions +description: Manage account-wide Email Sending suppression entries. +pcx_content_type: how-to +sidebar: + order: 6 +products: + - email-service +--- + +import { DashButton, Steps } from "~/components"; + +Manage recipients that Email Service must not contact. For suppression triggers and expiration rules, refer to [Suppression lists](/email-service/concepts/suppressions/). + +The dashboard and API are account-scoped. Entries apply to every sending domain and subdomain in the account. + +## View suppressions + + +1. In the Cloudflare dashboard, go to **Compute** > **Email Service** > **Email Sending**. + + + +2. Select **Suppressions**. + + +The table displays each recipient, reason, creation time, and expiration. **Never** means the entry has no scheduled expiration. + +## Add a suppression + + +1. In **Suppressions**, enter the recipient email address. +2. Select an expiration preset, a custom future time, or **Never**. +3. Select **Add**. + + +Entries created in the dashboard have the `manual` reason. They apply to every sending domain in the account. + +## Import suppressions + +You can paste addresses or upload `.csv`, `.json`, or `.txt` files. Supported file contents are: + +- `.csv` or `.txt`: Put one entry on each line as `` or `,`. Use an [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamp and omit the header row. +- `.json`: Use an array of address strings or objects. Each object requires `email` and can include an RFC 3339 `expires_at` timestamp. + + +1. In **Suppressions**, select **Import**. +2. Upload a supported file or paste the addresses. +3. Choose a default expiration for entries that omit one. +4. Select **Import**. Larger imports run in batches, so keep the dialog open until every batch finishes. + + +## Remove a suppression + +To remove a mutable entry, select **Delete** for that recipient. Read-only entries do not provide a delete action. + +Deleting an entry permits future delivery attempts. Verify that the recipient should receive mail before deleting an automatic suppression. + +## Use the API + +The [account Email Sending suppression management REST API](/api/resources/email_sending/subresources/suppressions/) supports listing, adding, importing, updating, and deleting entries. Requests require an [API token](/fundamentals/api/get-started/create-token/) with the **Email Sending: Edit** permission. + +API clients must use `read_only` to determine whether an entry is mutable. Do not infer mutability from the `reason` value. + +:::caution +Deleting a hard-bounce or complaint suppression permits delivery attempts to an address that already failed or reported your mail as spam. Verify the recipient before deleting the entry. +::: + +## Limits + +Each account can have one active entry per address. For page size, import, and rate limits, refer to [Suppression list limits](/email-service/platform/limits/#suppression-list-limits). diff --git a/src/content/docs/email-service/platform/limits.mdx b/src/content/docs/email-service/platform/limits.mdx index 064729b0962..27c06e8b82b 100644 --- a/src/content/docs/email-service/platform/limits.mdx +++ b/src/content/docs/email-service/platform/limits.mdx @@ -35,6 +35,20 @@ Sends to verified destination addresses are always free: they do not count towar | **Total message size** | 25 MiB | For [verified destination addresses](/email-service/configuration/email-routing-addresses/#destination-addresses) only | | **Header size** | 16 KB | All custom headers combined | +## Suppression list limits + +The following limits apply to the Email Sending [suppression list](/email-service/concepts/suppressions/) API: + +| Limit | Value | Notes | +| ------------------------- | ---------------- | --------------------------------------------------- | +| **Active entries** | 1 per address | Enforced independently for each account | +| **Results per page** | 1,000 | Maximum `per_page` value with a default of 100 | +| **Items per bulk import** | 1,000 | Split larger imports across several requests | +| **Bulk import requests** | 10 per minute | Applies per account and returns `429` when exceeded | +| **Note length** | 1,000 characters | The optional `note` field on an entry | + +The suppression list has no total-count field. Refer to the [list suppressions API reference](/api/resources/email_sending/subresources/suppressions/methods/list/) for pagination details. + ## Zone limits | Limit | Value | Notes | diff --git a/src/content/docs/email-service/reference/troubleshooting.mdx b/src/content/docs/email-service/reference/troubleshooting.mdx index 0521522fd3e..35d3702b95b 100644 --- a/src/content/docs/email-service/reference/troubleshooting.mdx +++ b/src/content/docs/email-service/reference/troubleshooting.mdx @@ -8,7 +8,7 @@ products: - email-service --- -import { DashButton } from "~/components"; +import { APIRequest, DashButton, Steps } from "~/components"; Email authentication is critical for successful email delivery. This guide helps you troubleshoot common SPF, DKIM, and DMARC issues with Email Service. @@ -202,6 +202,52 @@ To reduce bounce rates: 3. Monitor feedback loops: Subscribe to ISP feedback loops 4. Gradual warm-up: For new domains, start with small volumes +### Suppressed recipient + +Each sending domain has a [**Drop suppressed recipients** setting](/email-service/configuration/domains/#drop-suppressed-recipients). The setting is off by default. + +When the setting is off, the REST API returns `400`, the Workers binding throws `E_RECIPIENT_SUPPRESSED`, and SMTP rejects the message. Any suppressed recipient causes the send to fail. + +When the setting is on, Email Service removes suppressed recipients and processes the remaining recipients. If none remain, SMTP may return `250 2.0.0 Ok` without a Message-ID and deliver nothing. + +To investigate a suppressed recipient: + + +1. Query the exact recipient: + + + +2. Use the `reason`, `expires_at`, and `read_only` fields to choose an action. For the complete decision table, refer to [Suppression rules](/email-service/concepts/suppressions/#suppression-rules). +3. If `result` is empty, confirm that you queried the correct account. Then check the sending logs. +4. If the logs still report a suppression, [contact Cloudflare Support](/support/contacting-cloudflare-support/). + + +### Recipient blocked after expiration or deletion + +Expired entries stop appearing in the public list after their `expires_at` timestamp passes. Delivery enforcement can take additional time to stop. + +Updates and deletions also propagate asynchronously. The management list and delivery enforcement can briefly differ. + +To investigate delayed enforcement: + + +1. Confirm that the entry no longer appears in the account list. +2. Retry later because suppression updates propagate asynchronously. +3. If the recipient remains blocked, [contact Cloudflare Support](/support/contacting-cloudflare-support/). + + +### Bounces before suppression enforcement + +Bounce suppressions are created through background delivery processing. Messages already in progress can bounce before a new suppression takes effect. + +### Complaint suppression does not appear + +Complaint suppressions appear after Cloudflare receives and validates the provider report. The provider determines when that report arrives. + +### Missing suppression after a bounce + +Not every failure results in a suppression. Email Service creates automatic entries only for eligible recipient-side failures. Sender authentication, sender reputation, and unrelated infrastructure failures do not suppress the recipient. Check [Email sending logs](/email-service/observability/logs/) for the specific failure. + ### ISP-specific issues Different ISPs have specific requirements: