Comprehensive UTM tags documentation (backport of #712 to 7.1)

[promptless-for-oss]

Open in Promptless

Backports the comprehensive UTM tags documentation from user-documentation PR #712 onto the 7.1 branch, at the maintainer's request. It replaces the single thin docs/channels/utm_tags.rst page with a dedicated eight-page UTM Tags section under docs/utm_tags/ — an overview plus per-feature guides for Landing Pages, Asset downloads, Forms, Emails, Dynamic Web Content, Campaign conditions, and Segment filters. The two inbound :doc: links (from Focus Items and Dynamic Web Content) are repointed to the new overview, the old page is removed, the UTM Tags toctree caption is added to the docs index, and CPC/DWC are added to the Vale vocabulary.

A few objective RST defects present in the source PR (a nested .. note::, a malformed inline literal, and inconsistent casing inside example-URL code blocks) are corrected in this backport; a placeholder screenshot TODO in the Forms page is carried over as-is.

Trigger Events

• GitHub PR comment on mautic/user-documentation#712 requesting 7.1/7.2/6.0/5.2 backports

Synced from #712 code review (2026-08-14)
Applied maintainer @RCheesley's "Apply suggestions from code review" edits from #712 to keep this backport in step: swapped the placeholder example-URL host to example.com in docs/utm_tags/utm_tags_forms.rst and docs/utm_tags/utm_tags_landing_pages.rst (three sample URLs total). All three edits were applied verbatim. The third file changed on #712 (utm_tags_segment_filters.rst, an inline-literal typo fix on utm_content) needed no change here — that defect was already corrected in this backport, so it was a no-op.

---

Synced with #712 current head + outstanding review nits (2026-09-07)
At @adiati98's request (cherry-pick #712's newest reviewed commit into the backports, and apply the outstanding fixes here too), this backport is brought in step with #712's current head:

• Screenshot added — the leftover .. TODO: add screenshot marker on the Forms UTM page is replaced with the 'UTM tags recorded' Contact timeline screenshot (docs/channels/images/utm_tags/utm_tags_recorded_timeline.png). (Supersedes the earlier "TODO carried over as-is" note.)
• Record UTM Tags action-label casing — matches the on-screen label (verified against mautic/mautic LeadBundle messages.ini): fixed in utm_tags_forms.rst, utm_tags_campaign_conditions.rst, and the utm_tags_overview.rst feature-group table.
• Host swap yoursite.com/your-mautic.com → example.com in utm_tags_emails.rst and utm_tags_asset_downloads.rst (matches RCheesley's merged host decision on EVERYTHING about UTM tags in Mautic #712).
• API payload keys referrer→referer, User_agent→user_agent in the utm_tags_overview.rst REST bullet.
• Copy/grammar — UTM tags - Urchin Tracking Module - are intro fix; DWC component line narrowed to "tracked links in Dynamic Web Content"; emails step "links in the Email"; terminal period on the DWC page.

Both items previously flagged for your call are now resolved per your reply on #712:

1. Condition paths → green/red wording — switched the Yes/No output-path references (intro, numbered step, and warning) in utm_tags_campaign_conditions.rst to the green/red path terminology the Campaign Builder UI actually uses (green = match, red = no match). Verified against mautic/mautic app/bundles/CampaignBundle/Assets/js/campaign.js: a Contact field value condition node draws a green connector for the match path (--support-success-inverse) and a red connector for the no-match path (--support-error-inverse), with no literal Yes/No text — confirmed identical across 5.2, 6.0, 7.0, 7.1, and 7.2. Matches this repo's own campaign_builder.rst ("Green paths"/"Red paths").
2. Grammar — step lines read Open the … and edit its details: (dropped the stray "the"; kept the "its" wording).

The GA-ID screenshot on this branch remains add_google_analytics_id.png. Vale is clean on all changed lines.

[promptless-for-oss]

Verbatim backport (7.0 to 7.1) of the UTM tags documentation set authored and reviewed in PR #712. All eight new pages under docs/utm_tags/ (overview, landing pages, asset downloads, forms, emails, dynamic web content, campaign conditions, segment filters) reproduce PR #712's reviewed prose; product-behavior claims are inherited from that review and are not independently re-verifiable here since the Mautic application source is not in this docs repo. Only objective RST-defect fixes were applied during backport (duplicate nested .. note:: directive removed in utm_tags_landing_pages.rst; malformed inline-literal closing backtick fixed in utm_tags_segment_filters.rst; inconsistent utm_medium=Email capitalization normalized to lowercase email in four example URLs) — none altered meaning.

Source: #712

[promptless-for-oss]

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.