Skip to content

Commit 6c11e33

Browse files
committed
docs: audit and improve email service docs for accuracy
- Merge reference/limits into platform/limits, add sending limits section - Fix DNS records to match dashboard: sending records on cf-bounce subdomain, correct SPF (_spf.mx.cloudflare.net), correct DKIM selectors, add sending MX - Update dashboard nav paths: Compute & AI -> Compute, add Email Sending/Routing - Remove global suppression list concept, keep account suppression list only - Remove inaccurate sections (custom sending domains, sender restrictions, multi-domain setup, domain health monitoring) - Add remote bindings (recommended) to local dev sending docs - Fix routing local dev: remove wrong Content-Type header, note Message-ID required - Add rejected status for suppressed emails in logs - Add separate domains best practice to deliverability page - Add redirect for reference/limits -> platform/limits
1 parent 0b7bffd commit 6c11e33

File tree

24 files changed

+373
-579
lines changed

24 files changed

+373
-579
lines changed

public/__redirects

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
# STATIC REDIRECTS
44
# ============================================================================
55

6+
# Email Service
7+
/email-service/reference/limits/ /email-service/platform/limits/ 301
8+
69
# homepage
710
/docs/ /directory/ 301
811
/support/ai/ / 301

src/content/docs/email-routing/email-workers/index.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ With Email Workers you can leverage the power of Cloudflare Workers to implement
99

1010
Creating your own rules with Email Workers is as easy or complex as you want. You can begin using one of the starter templates that are pre-populated with code for popular use-cases. These templates allow you to create a blocklist, allowlist, or send notifications to Slack.
1111

12-
If you prefer, you can skip the templates and use custom code. You can, for example, create logic that only accepts messages from a specific address, and then forwards them to one or more of your verified email addresses, while also alerting you on Slack.
12+
If you prefer, you can skip the templates and use custom code. You can, for example, create logic that only accepts messages from a specific address, and then forwards them to one or more of your [verified email addresses](/email-service/configuration/email-routing-addresses/#destination-addresses), while also alerting you on Slack.
1313

1414
The following is an example of an allowlist Email Worker:
1515

src/content/docs/email-service/concepts/deliverability.mdx

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ sidebar:
66
order: 3
77
---
88

9-
import {DashButton, Render} from "~/components";
9+
import { DashButton, Render } from "~/components";
1010

11-
Email deliverability ensures your emails reach recipients' inboxes. Cloudflare Email Service handles bounces automatically and manages sender reputation to maximize delivery success.
11+
When you send an email, there is no guarantee it reaches the recipient's inbox. Inbox providers like Gmail, Yahoo, Outlook, and iCloud invest heavily in filtering out unwanted email. If you send poorly targeted emails, have high bounce rates, or trigger spam complaints, these providers may flag your domain as untrustworthy. Once that happens, even your legitimate emails can end up in spam or be blocked outright.
12+
13+
This concept is referred to as email deliverability: maintaining a healthy sending reputation so that inbox providers trust your emails. Cloudflare Email Service helps with this by automatically handling bounces, managing suppression lists, and authenticating your emails through SPF, DKIM, and DMARC.
1214

1315
## Bounces
1416

@@ -47,10 +49,10 @@ Cloudflare automatically manages:
4749
- **Domain authentication**: DKIM signing, SPF alignment, DMARC compliance
4850
- **Feedback processing**: ISP complaint handling and suppression list management
4951

50-
Monitor your reputation and delivery metrics in the Cloudflare dashboard.
51-
5252
### Best practices
5353

54+
#### Content and list hygiene
55+
5456
Avoid content that can trigger spam-detection or can be perceived as unwanted content:
5557

5658
- Avoid spam trigger words (FREE, URGENT, GUARANTEED)
@@ -63,8 +65,18 @@ Ensure that your email lists are clean and contain intended recipients:
6365
- Implement double opt-in for subscriptions
6466
- Remove hard bounced addresses immediately
6567

66-
Ensure that you deliverability stays above key metrics to avoid affecting your email sending reputation:
68+
Ensure that your deliverability stays above key metrics to avoid affecting your email sending reputation:
6769

6870
- Delivery rate >95%
6971
- Hard bounce rate < 2%
7072
- Complaint rate < 0.1%
73+
74+
#### Use separate domains for separate purposes
75+
76+
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:
77+
78+
- `notifications.yourdomain.com` for transactional emails (order confirmations, password resets)
79+
- `marketing.yourdomain.com` for marketing and promotional emails
80+
- `yourdomain.com` for important account-related communications
81+
82+
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/).

src/content/docs/email-service/concepts/email-authentication.mdx

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,19 @@ Email authentication verifies sender identity and improves deliverability. **Clo
1212

1313
SPF ensures that no one else can send emails with your domain by authorizing which mail servers are allowed to send on your behalf.
1414

15-
**Required SPF record:**
15+
Email Service configures separate SPF records for sending and routing:
1616

17-
```dns
18-
TXT yourdomain.com "v=spf1 include:_spf.email.cloudflare.net ~all"
19-
```
17+
- **Email Sending** SPF record on `cf-bounce.yourdomain.com`:
18+
19+
```dns
20+
TXT cf-bounce.yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all"
21+
```
22+
23+
- **Email Routing** SPF record on the root domain:
24+
25+
```dns
26+
TXT yourdomain.com "v=spf1 include:_spf.mx.cloudflare.net ~all"
27+
```
2028

2129
SPF works by:
2230

@@ -36,11 +44,10 @@ DKIM ensures that emails have not been tampered during transit by cryptographica
3644
3. Public key is published in DNS
3745
4. Recipients use the public key to verify the signature
3846

39-
**DNS record example:**
47+
Email Service uses separate DKIM selectors for sending and routing:
4048

41-
```dns
42-
TXT selector1._domainkey.yourdomain.com "v=DKIM1; k=rsa; p=MIGfMA0..."
43-
```
49+
- **Email Sending**: `cf-bounce._domainkey.yourdomain.com`
50+
- **Email Routing**: `cf2024-1._domainkey.yourdomain.com`
4451

4552
Cloudflare automatically generates and manages DKIM keys. You add the provided DNS records from the dashboard.
4653

@@ -74,4 +81,4 @@ Email authentication provides:
7481
- **Security**: Protects your domain from spoofing
7582
- **Reputation**: Maintains good sender reputation with ISPs
7683

77-
Cloudflare Email Service handles authentication automatically, but you need to configure the DNS records for SPF, DKIM, and DMARC as provided in your dashboard.
84+
Cloudflare Email Service handles authentication automatically, but you need to configure the DNS records for SPF, DKIM, and DMARC as provided in your dashboard. Email Sending and Email Routing use separate DNS records -- refer to [Domain configuration](/email-service/configuration/domains/) for the full details.

src/content/docs/email-service/concepts/email-lifecycle.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ Every email sent through Cloudflare Email Service follows this processing pipeli
1717

1818
```mermaid
1919
flowchart LR
20-
A[Request Received] --> B[Rate Limit Check] --> C[Authentication & Reputation] --> D[Suppression Check] --> E[Delivery Attempt]
20+
A[Request Received] --> B["Rate Limit, Authentication & Suppression Check"] --> E[Delivery Attempt]
2121
E --> G{Success?}
22-
G -->|Yes| F[Final Status & Metrics]
22+
G -->|Yes, successfully delivered| F[Final Status & Metrics]
2323
G -->|No - Soft Bounce| H[Retry with Exponential Backoff]
2424
G -->|No - Hard Bounce| F
2525
H --> E
@@ -39,7 +39,7 @@ flowchart LR
3939

4040
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.
4141

42-
4. **Suppression list check:** The system checks the recipient against global suppression lists that include bounces, complaints, and unsubscribes. Recipients found on these lists are blocked from receiving the email.
42+
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.
4343

4444
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:
4545
- **Soft bounces (4xx responses)**: The system retries delivery using exponential backoff timing

src/content/docs/email-service/concepts/suppressions.mdx

Lines changed: 5 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,44 +11,18 @@ import { Tabs, TabItem } from "~/components";
1111

1212
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.
1313

14-
## Suppression lists
14+
## Account suppression list
1515

16-
There are 2 types of suppression lists that can prevent emails from being sent to an email address in order to ensure high deliverability:
16+
Cloudflare automatically manages suppressions for your account to preserve your reputation as an email sender.
1717

18-
- Cloudflare's global suppression list (maintained by Cloudflare)
19-
- Your account's specific suppression list
20-
21-
### Global suppression list
22-
23-
The global suppression list is a list of emails
24-
that have been flagged as problematic. Cloudflare Email Service will not send emails to email
25-
addresses on this global suppression list to preserve the reputation of the shared IP pool used for sending emails.
26-
27-
Here are the factors that Cloudflare Email Service uses to determine emails to add to the global suppression list:
28-
29-
- **Hard bounces**: Permanently invalid addresses
30-
- **Repeated soft bounces**: Addresses that consistently fail delivery
31-
- **Manual additions**: Addresses Cloudflare specifically blocks
32-
- **Compliance blocks**: Legal or regulatory requirements
33-
34-
### Account suppression list
35-
36-
Cloudflare also automatically manages suppressions for your account to preserve your reputation as an email sender.
37-
38-
Cloudflare will automatically add email addresses to your account suppression list for the following reason:
18+
Cloudflare will automatically add email addresses to your account suppression list for the following reasons:
3919

20+
- **Hard bounces**: Invalid or non-existent email addresses are immediately suppressed.
21+
- **Repeated soft bounces**: Addresses that repeatedly fail delivery are temporarily or permanently suppressed based on the frequency and pattern of failures.
4022
- **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.
4123

4224
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.
4325

44-
## Automatic suppression logic
45-
46-
Cloudflare automatically suppresses addresses that:
47-
48-
- **Hard bounce**: Invalid or non-existent email addresses are immediately added to the Cloudflare global suppression list.
49-
- **Repeated soft bounces**: Addresses that repeatedly fail delivery are temporarily or permanently suppressed based on the frequency and pattern of failures.
50-
- **Spam complaints**: Recipients who mark emails as spam are added to your account suppression list.
51-
5226
## Best practices
5327

5428
### List hygiene

0 commit comments

Comments
 (0)