Migrate more email routing docs to email service

thomasgauvin · thomasgauvin · commit 0b7bffdee9e3 · 2026-04-15T15:11:01.000-04:00
diff --git a/src/content/docs/email-routing/index.mdx b/src/content/docs/email-routing/index.mdx
@@ -22,6 +22,12 @@ Create custom email addresses for your domain and route incoming emails to your
 
 </Description>
 
+:::note[Email Routing is now part of Email Service]
+Email Routing is now integrated into [Cloudflare Email Service](/email-service/), a complete email product suite. Email Service provides all the routing capabilities you already use, plus the ability to send emails from Workers or external servers using a REST API.
+
+For new projects, refer to the [Email Service documentation](/email-service/). Existing Email Routing configurations continue to work without changes.
+:::
+
 <Plan id="email.email_routing.properties.availability.summary" />
 
 <Render file="email-routing-definition" product="email-routing" />
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
@@ -149,22 +149,34 @@ A successful response returns the delivery status for each recipient:
 
 ## Error handling
 
-The REST API returns standard Cloudflare API error responses. A failed request returns an `errors` array with numeric error codes:
+The REST API returns standard Cloudflare API error responses. A failed request returns an `errors` array with numeric error codes and machine-readable messages:
 
 ```json
 {
   "success": false,
   "errors": [
     {
-      "code": 1000,
-      "message": "Sender domain not verified"
+      "code": 10001,
+      "message": "email.sending.error.invalid_request_schema"
     }
   ],
   "messages": [],
   "result": null
 }
 ```
 
+Common REST API error codes:
+
+| HTTP Status | Code | Message | Description |
+| ----------- | ---- | ------- | ----------- |
+| 400 | 10001 | `email.sending.error.invalid_request_schema` | Invalid request format |
+| 400 | 10200 | `email.sending.error.email.invalid` | Invalid email content |
+| 400 | 10201 | `email.sending.error.email.no_content_length` | Missing content length |
+| 400 | 10202 | `email.sending.error.email.too_big` | Email exceeds size limit |
+| 403 | 10203 | `email.sending.error.email.sending_disabled` | Sending disabled for this zone/account |
+| 429 | 10004 | `email.sending.error.throttled` | Rate limit exceeded |
+| 500 | 10002 | `email.sending.error.internal_server` | Internal server error |
+
 :::note[Workers binding vs REST API errors]
 The REST API returns standard Cloudflare API numeric error codes, while the [Workers binding](/email-service/api/send-emails/workers-api/) throws errors with string codes (for example, `E_SENDER_NOT_VERIFIED`). Refer to the [Workers API error codes table](/email-service/api/send-emails/workers-api/#error-codes) for the string error codes.
 :::
diff --git a/src/content/docs/email-service/concepts/email-lifecycle.mdx b/src/content/docs/email-service/concepts/email-lifecycle.mdx
@@ -52,7 +52,6 @@ flowchart LR
 
 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
-   - **Bounced**: The email permanently failed delivery (hard bounce) or exceeded the maximum retry attempts (soft bounce)
----
+   - **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/).
 
 Understanding the email lifecycle helps you build robust email applications that handle all possible outcomes and provide excellent user experiences through proper status tracking and error handling.
diff --git a/src/content/docs/email-service/configuration/domains.mdx b/src/content/docs/email-service/configuration/domains.mdx
@@ -338,6 +338,7 @@ export default {
 				from: "contact@company.com",
 				to: "client@example.com",
 				subject: "Corporate Communication",
+				text: "Thank you for your business.",
 			});
 		}
 
@@ -346,6 +347,7 @@ export default {
 				from: "updates@product.company.com",
 				to: "user@example.com",
 				subject: "Product Update",
+				text: "We have a new product update for you.",
 			});
 		}
 	},
@@ -369,6 +371,39 @@ Removing a domain will:
 - Require reconfiguration if re-added
   :::
 
+### DNS record management
+
+When you remove a domain from Email Service, you have two options for handling the DNS records:
+
+**Option 1: Remove all records**
+
+This removes all Email Service DNS records from your domain:
+
+- All SPF, DKIM, and MX records for Email Service are deleted
+- Your domain will no longer receive or send emails through Email Service
+- If you want to use Email Service again in the future, you will need to onboard the domain and add all records from scratch
+
+**Option 2: Keep records**
+
+This keeps the DNS records in place but disables Email Service:
+
+- DNS records remain in your domain configuration
+- Email Service stops processing emails for the domain
+- You can re-enable Email Service by onboarding the domain again
+- DNS records that were automatically added will remain locked to prevent accidental deletion
+
+To modify locked records after removal:
+
+1. Go to your domain's **DNS** > **Records**.
+2. Find the locked Email Service records.
+3. Select the record and choose **Edit**.
+4. Toggle **Unlock record** to enable editing.
+5. Make your changes and save.
+
+:::note
+Keeping records is useful if you plan to re-enable Email Service later. Removing records is recommended if you are migrating to a different email provider.
+:::
+
 ### Transfer domain ownership
 
 1. Domain must remain in the same Cloudflare account.
diff --git a/src/content/docs/email-service/configuration/email-routing-addresses.mdx b/src/content/docs/email-service/configuration/email-routing-addresses.mdx
@@ -66,6 +66,17 @@ Your email rule is now disabled. It will not forward emails to a destination add
 3. In **Custom addresses**, identify the email rule you want to edit, and select **Edit**.
 4. Make the appropriate changes to this custom address.
 
+### Delete a custom address
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/) and select your account and domain.
+2. Go to **Email** > **Email Routing** > **Routes**.
+3. In **Custom addresses**, identify the email rule you want to delete.
+4. Select **Delete** and confirm the action.
+
+:::warning
+Deleting a custom address will permanently remove the routing rule. Emails sent to this address will no longer be routed. If you want to temporarily stop routing without deleting the rule, refer to [Disable an email rule](#disable-an-email-rule).
+:::
+
 ## Catch-all address
 
 When you enable this feature, Email Routing will catch variations of email addresses to make them valid for the specified domain. For example, if you created an email rule for `info@example.com` and a sender accidentally types `ifno@example.com`, the email will still be correctly handled if you have **Catch-all addresses** enabled.
diff --git a/src/content/docs/email-service/configuration/mta-sts.mdx b/src/content/docs/email-service/configuration/mta-sts.mdx
@@ -0,0 +1,76 @@
+---
+title: Configure MTA-STS
+pcx_content_type: how-to
+sidebar:
+  order: 4
+---
+
+import { DashButton } from "~/components";
+
+MTA Strict Transport Security ([MTA-STS](https://datatracker.ietf.org/doc/html/rfc8461)) was introduced by email service providers including Microsoft, Google and Yahoo as a solution to protect against downgrade and man-in-the-middle attacks in SMTP sessions, as well as solving the lack of security-first communication standards in email.
+
+Suppose that `example.com` is your domain and uses Email Service. Here is how you can enable MTA-STS for it.
+
+1. In the Cloudflare dashboard, go to the **Records** page.
+
+   <DashButton url="/?to=/:account/:zone/dns/records" />
+
+2. Create a new CNAME record with the name `_mta-sts` that points to Cloudflare’s record `_mta-sts.mx.cloudflare.net`. Make sure to disable the proxy mode.
+
+![MTA-STS CNAME record](~/assets/images/email-routing/mta-sts-record.png)
+
+3. Confirm that the record was created:
+
+```sh
+dig txt _mta-sts.example.com
+```
+
+```sh output
+_mta-sts.example.com. 300 IN  CNAME _mta-sts.mx.cloudflare.net.
+_mta-sts.mx.cloudflare.net. 300 IN  TXT "v=STSv1; id=20230615T153000;"
+```
+
+This tells the other end client that is trying to connect to us that we support MTA-STS.
+
+Next you need an HTTPS endpoint at `mta-sts.example.com` to serve your policy file. This file defines the mail servers in the domain that use MTA-STS. The reason why HTTPS is used here instead of DNS is because not everyone uses DNSSEC yet, so we want to avoid another MITM attack vector.
+
+To do this you need to deploy a Worker that allows email clients to pull Cloudflare’s Email Service policy file using the “well-known” URI convention.
+
+4. Go to your **Account** > **Workers & Pages** and select **Create**. Pick the default "Hello World" option button, and replace the sample worker code with the following:
+
+```js
+export default {
+	async fetch(request, env, ctx) {
+		return await fetch(
+			"https://mta-sts.mx.cloudflare.net/.well-known/mta-sts.txt",
+		);
+	},
+};
+```
+
+This Worker proxies `https://mta-sts.mx.cloudflare.net/.well-known/mta-sts.txt` to your own domain.
+
+5. After deploying it, go to the Worker configuration, then **Settings** > **Domains & Routes** > **+Add**. Type the subdomain `mta-sts.example.com`.
+
+![MTA-STS Worker Custom Domain](~/assets/images/email-routing/mta-sts-domain.png)
+
+You can then confirm that your policy file is working with the following:
+
+```sh
+curl https://mta-sts.example.com/.well-known/mta-sts.txt
+```
+
+```sh output
+version: STSv1
+mode: enforce
+mx: *.mx.cloudflare.net
+max_age: 86400
+```
+
+This says that you domain `example.com` enforces MTA-STS. Capable email clients will only deliver email to this domain over a secure connection to the specified MX servers. If no secure connection can be established the email will not be delivered.
+
+Email Service also supports MTA-STS upstream, which greatly improves security when forwarding your emails to service providers like Gmail, Microsoft, and others.
+
+---
+
+For more information about domain security and email authentication, refer to [Email authentication](/email-service/concepts/email-authentication/).
diff --git a/src/content/docs/email-service/examples/email-sending/signup-flow.mdx b/src/content/docs/email-service/examples/email-sending/signup-flow.mdx
@@ -73,7 +73,7 @@ async function handleSignup(request: Request, env: Env): Promise<Response> {
 
 	// Generate verification token (expires in 1 hour)
 	const verificationToken = crypto.randomUUID();
-	await env.VERIFICATION_TOKENS.put(verificationToken, userId, {
+	await env.VERIFICATION_TOKENS.put(verificationToken, email, {
 		expirationTtl: 3600,
 	});
 
@@ -124,13 +124,13 @@ async function handleVerification(
 	}
 
 	// Verify token
-	const userId = await env.VERIFICATION_TOKENS.get(token);
-	if (!userId) {
+	const userEmail = await env.VERIFICATION_TOKENS.get(token);
+	if (!userEmail) {
 		return new Response("Invalid or expired token", { status: 400 });
 	}
 
 	// Get and update user
-	const userData = await env.USERS.get(`user:${userId}`);
+	const userData = await env.USERS.get(userEmail);
 	if (!userData) {
 		return new Response("User not found", { status: 404 });
 	}
diff --git a/src/content/docs/email-service/observability/logs.mdx b/src/content/docs/email-service/observability/logs.mdx
@@ -18,7 +18,7 @@ For outbound emails sent through Email Service:
 
 - **Sent**: Email successfully accepted and queued for delivery
 - **Delivered**: Email successfully delivered to recipient's mail server
-- **Bounced**: Email bounced (hard or soft bounce)
+- **Delivery failed**: Email bounced (hard or soft bounce). This corresponds to the `deliveryFailed` status in the [GraphQL Analytics API](/email-service/observability/metrics-analytics/).
 - **Failed**: Email failed to send due to configuration or authentication issues
 
 ### Email routing logs
@@ -86,7 +86,7 @@ Based on the information shown in email details, you can:
 
 Use the Activity Log filters to find specific emails:
 
-- **By status**: Filter by delivery status (for example: sent, bounced, delivered)
+- **By status**: Filter by delivery status (for example: sent, delivered, delivery failed)
 - **By timeframe**: View logs for specific date ranges
 - **By sender/recipient**: Search for specific email addresses
 - **By authentication**: Filter by SPF/DKIM/DMARC results
diff --git a/src/content/docs/email-service/observability/metrics-analytics.mdx b/src/content/docs/email-service/observability/metrics-analytics.mdx
