[Email] add Google Workspace MX conflict guidance to troubleshooting

[ngayerie]

Add a section to the Email Service troubleshooting page explaining that Cloudflare Email Routing and Google Workspace MX records cannot coexist on the same domain, with steps to switch between them and a subdomain workaround.

DEE-3619

[cloudflare-docs-bot]

Review

⚠️ 1 warning found in commit 86590ad.

👉 Fix in your agent 👈

Fix the following review findings in PR #33286 (https://github.com/cloudflare/cloudflare-docs/pull/33286).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Warnings (1)

#### CR-30af796f235e · Broken internal link
- **File:** `src/content/docs/email-service/reference/troubleshooting.mdx` line 225
- **Issue:** The link to `/dns/manage-dns-records/how-to/set-up-google-workspace/` points to a page that does not exist in the repository: repo search shows no `set-up-google-workspace.mdx` anywhere, and the `dns/manage-dns-records/how-to/` directory contains only `email-records`, `create-dns-records`, `create-zone-apex`, `create-subdomain`, `batch-record-changes`, `import-and-export`, `round-robin-dns`, `subdomains-outside-cloudflare`, and `managing-dynamic-ip-addresses`. The link will 404 for readers.
- **Fix:** Point the link at an existing page that documents the record values, such as `/dns/manage-dns-records/how-to/email-records/` (Set up email records), or add the referenced `set-up-google-workspace` page as part of this PR.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (1)

File

Issue

email-service/reference/troubleshooting.mdx line 225

Broken internal link — The link to /dns/manage-dns-records/how-to/set-up-google-workspace/ points to a page that does not exist in the repository: repo search shows no set-up-google-workspace.mdx anywhere, and the dns/manage-dns-records/how-to/ directory contains only email-records, create-dns-records, create-zone-apex, create-subdomain, batch-record-changes, import-and-export, round-robin-dns, subdomains-outside-cloudflare, and managing-dynamic-ip-addresses. The link will 404 for readers. Fix: Point the link at an existing page that documents the record values, such as /dns/manage-dns-records/how-to/email-records/ (Set up email records), or add the referenced set-up-google-workspace page as part of this PR.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
*	@cloudflare/product-owners

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://ngayerie-dee-3619-email-service-gw-conflict.previews.developers.cloudflare.com (commit 86590ad)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://89d79c17.previews.developers.cloudflare.com	86590ad	2026-09-08T16:14:14.637Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://aca683fb.previews.developers.cloudflare.com	ffec608	2026-09-08T14:18:17.889Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://eea13dc6.previews.developers.cloudflare.com	8572cdf	2026-09-08T12:23:31.493Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://06ef2197.previews.developers.cloudflare.com	84d00d4	2026-09-08T10:07:26.426Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://03e44f8e.previews.developers.cloudflare.com	faa6cae	2026-09-08T08:56:10.645Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://5cb620a4.previews.developers.cloudflare.com	695c8df	2026-09-07T23:54:06.391Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://217c8116.previews.developers.cloudflare.com	0476d4b	2026-09-07T23:24:37.898Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://928117c9.previews.developers.cloudflare.com	0630066	2026-09-07T22:53:42.119Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://e4a2165b.previews.developers.cloudflare.com	26f4ac9	2026-09-07T22:26:13.853Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://b7f32745.previews.developers.cloudflare.com	3d52356	2026-09-07T22:01:50.480Z	Visit the dashboard ↗

View all previews: View all previews ↗

[github-actions]

Preview URL: https://86590ade.preview.developers.cloudflare.com
Preview Branch URL: https://ngayerie-dee-3619-email-service-gw-conflict.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/email-service/reference/troubleshooting/	https://ngayerie-dee-3619-email-service-gw-conflict.preview.developers.cloudflare.com/email-service/reference/troubleshooting/

[ngayerie]

[AI] Addressing SG-cf2912634141: replacing notifications.yourdomain.com with notifications.example.com (RFC 2606 reserved domain).

[ngayerie]

[AI] Triage for PR #33286:

• CR-8495eacd8b81 ✅ Agree — fixing nav path to Compute > Email Service > Email Routing with <DashButton>.
• CR-cc9f01b1c047 ✅ Agree — reordering steps to match domains.mdx guidance: unlock DNS records first, add Google MX records alongside them, then disable Email Routing to avoid any mail interruption.

[ngayerie]

[AI] Triage for PR #33286 (round 2):

• CR-6a6b06c12d2e — Skipping. The link to /dns/manage-dns-records/how-to/set-up-google-workspace/ is intentional and correct — the target page is being created in PR [DNS] document Google Workspace DNS record setup #33285 as part of the same DEE-3619 work. It will resolve once [DNS] document Google Workspace DNS record setup #33285 merges before or alongside this PR. Pointing to vendor-specific-records would send readers to a less complete reference.
• SG-a29d8e49ff81 ✅ Fix — disabling Email Routing → turning off Email Routing.
• SG-cd00db8bcf07 ✅ Fix — disable Email Routing → turn off Email Routing.

[ngayerie]

[AI] Triage for PR #33286 (round 3):

• CR-ef2492d4c079 ✅ Fix — Agree. Adding a step to replace the SPF record before turning off Email Routing, using the merged include from domains.mdx: v=spf1 include:_spf.google.com ~all.
• SG-4aec43f1ddbb ✅ Fix — Wrapping MX and SPF in backticks.

[ngayerie]

[AI] Triage PR #33286 (round 4):

• CR-890461b4e7f9 ✅ Fix — Correct. Step 5 will merge both includes (include:_spf.mx.cloudflare.net include:_spf.google.com) while Email Routing is still active, so forwarded mail keeps passing SPF. Step 6 then turns off Email Routing; step 7 will advise dropping the Cloudflare include after routing is confirmed off.
• CR-29e46c8e1d21 ✅ Fix — Adding a note that during the brief DNS propagation window mail may be split between the two paths and to complete the steps quickly.
• SG-f2993582bdf2 ✅ Fix — Wrapping all bare SPF instances on line 232 in backticks.

[ngayerie]

[AI] Triage PR #33286 (round 5):

• CR-0536be73aa81 ✅ Fix — Adding the 10-DNS-lookup-limit caveat from domains.mdx and softening the guarantee.
• CR-8062a677883f ✅ Fix — Clarifying that only Cloudflare-managed (locked) records are removed when Email Routing is turned off; user-edited (unlocked) records survive. Step 7 is an edit of the surviving record.

[ngayerie]

[AI] Triage PR #33286 (round 6):

• CR-3fda21976d95 ✅ Fix — Linking to #remove-a-domain-from-email-routing (the section that describes the record-removal behavior) instead of the non-existent #spf-records.
• CR-2690c0405478 ✅ Fix — Aligning with domains.mdx: disabling Email Routing removes all routing-related DNS records it added (MX, SPF, DKIM). The merged SPF is removed, so step 7 now re-adds a fresh Google-only SPF record.

[ngayerie]

[AI] Triage PR #33286 (round 7):

• CR-1fbd70f24088 ✅ Fix — Step 7 will say "update the existing SPF record" instead of "add a new" to avoid duplicate SPF records.
• CR-6c6c6c616006 ✅ Fix — Pointing the 10-DNS-lookup-limit link to #routing-records (where the SPF lookup-limit note lives) instead of #remove-a-domain-from-email-routing.

[ngayerie]

[AI] Triage PR #33286 (round 8):

• CR-1ac71a2fc092 ✅ Fix — Rewriting step 7 to instruct users to check for any remaining v=spf1 record and update it in place (or add one if none exists), avoiding the duplicate SPF risk.

[ngayerie]

[AI] Triage PR #33286 (round 9):

• CR-379ca2be1c44 ✅ Fix — Agree. Step 7 will instruct users to remove only include:_spf.mx.cloudflare.net from the existing record and ensure include:_spf.google.com is present, rather than replacing the entire record.

[ngayerie]

[AI] Triage PR #33286 (round 10):

• CR-9b294ae3536b ✅ Fix — The root cause is that step 6 claims Email Routing removes MX, SPF, and DKIM, but the SPF was unlocked and manually edited in steps 3 and 5 and is therefore no longer Email Service-managed. Per domains.mdx: it removes records "that Email Service added" — not user-edited records. Fixing step 6 to state that only the MX and DKIM records (which remain managed) are removed; the unlocked SPF from step 5 stays in place. This makes step 7 (update the surviving SPF) consistent.

[ngayerie]

[AI] Triage PR #33286 (round 11):

• CR-be21e270eaea ✅ Fix — Agreed. The "unlocked SPF survives" assumption contradicts domains.mdx and cannot be reliably stated without platform-level confirmation. Removing the assumption entirely.
• CR-35ae4eddb906 ✅ Fix — Agreed. The asymmetry between MX and SPF unlock behavior is unexplained and confusing. Removing the unlock step for both records — it is not needed. You can add new MX records alongside locked ones; Email Routing removes its own locked records when disabled.
• SG-1cca346aa85f ✅ Fix — Splitting semicolon into two sentences.

Rewriting the procedure as the simplest correct version: (1) add Google MX records, (2) turn off Email Routing (removes all CF routing records cleanly), (3) add a new Google-only SPF. No unlock, no dual-SPF, no ambiguity.

[ngayerie]

[AI] Skipping CR-30af796f235e — the link to /dns/manage-dns-records/how-to/set-up-google-workspace/ is intentional. That page is being created by companion PR #33285 ([DNS] document Google Workspace DNS record setup), which is part of the same DEE-3619 work. The link will resolve once both PRs are merged. These two PRs should be merged together or #33285 first.

[ngayerie]

Hi @thomasgauvin
Would it be possible for you to review this PR?
Thanks!