EVERYTHING about UTM tags in Mautic

[andersonjeccel]

Description

This PR adds docs about literally every information found in backend about how UTM tags work in all features.
Covers more than 14 features.
A lot of info that there's nowhere in the internet available, since investigation was done in backend to get a full picture.

Linked issue

Screenshots or screen recordings

[adiati98]

Hey @andersonjeccel,

Thanks for the PR!

I'd like to confirm here.
From which version does this docs apply? Is it since M5?

TIA! ✨

cc: @escopecz

[andersonjeccel]

@adiati98 Yes, 5

[adiati98]

@andersonjeccel quick question. Is "Pages" here (and across the files) mean "Landing Pages"? Or just "pages" in general?

[adiati98]

@andersonjeccel can you please confirm here? TIA!

[andersonjeccel]

Yes, Landing pages
Can we ask Promptless to fix?

[adiati98]

So far we can't ask Promptless to fix PR that it didn't create. So, I'll fix them manually. 🙂

[adiati98]

@andersonjeccel sorry for taking me a while to get to this. There are a couple of things:

• I see a potential of huge amount of request changes regarding to grammar and style. Do you mind if I go ahead and fix them locally?
• Can you please confirm this comment?

Thanks!

[andersonjeccel]

@adiati98 yes, thank you so much

[promptless-for-oss]

Progress: the first backport is up — a 7.1 version of this UTM tags documentation (#921). Working on the 7.2, 6.0, and 5.2 versions next.

[promptless-for-oss]

Progress: the 7.2 version is now up too (#922). Next up are the 6.0 and 5.2 versions.

[promptless-for-oss]

Progress: the 6.0 version is up (#923). Just the 5.2 version left.

[promptless-for-oss]

Done! I've opened backport PRs of this UTM tags documentation for all four requested branches:

• 7.1 — Comprehensive UTM tags documentation (backport of #712 to 7.1) #921
• 7.2 — Comprehensive UTM tags documentation (backport of #712 to 7.2) #922
• 6.0 — Comprehensive UTM tags documentation (backport of #712 to 6.0) #923
• 5.2 — Comprehensive UTM tags documentation (backport of #712 to 5.2) #924

Each mirrors the new eight-page UTM Tags section from this PR. On 6.0 and 5.2 the Google Analytics screenshot reference was adjusted to the image filename those branches use (add_ga_code.png). I also cleaned up a few small RST issues carried over from the source (a nested note, a malformed inline literal, and lowercased the UTM values inside the example URLs).

Heads-up: each PR shows a failing build check, but it's a pre-existing broken external link (aivie.ch) in an unrelated page that fails the link-checker on all of these branches — it isn't caused by these docs and needs no change here.

[RCheesley]

@promptless-for-oss there are some small changes to this PR, please can you cherry pick and sync them over to the other version's PRs? Thanks!

[promptless-for-oss]

Thanks @RCheesley — will do. I'll pull the small changes from this PR and sync them across the other version PRs for the UTM tags docs, then follow up here with a rundown of what went where.

[promptless-for-oss]

Found the changes — they're the "Apply suggestions from code review" edits: normalizing example URL hosts to example.com in the UTM tags forms and landing-pages pages, plus a small typo fix in the utm_content inline literal in the segment-filters page. Syncing the same edits into the parallel open PRs for the other versions now, and I'll report back here with a per-version rundown.

[Copilot]

Pull request overview

This PR replaces the previous single-page UTM Tags documentation with a dedicated, more detailed UTM Tags section that explains how Mautic captures, appends, stores, and uses UTM parameters across multiple features.

Changes:

• Added a new docs/utm_tags/ documentation set covering UTM capture, outbound tagging, and targeting (segments/campaign conditions).
• Updated documentation navigation and cross-references to point to the new UTM Tags overview.
• Updated Vale vocabulary to accept newly introduced acronyms used in the docs (e.g., CPC, DWC).

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
docs/utm_tags/utm_tags_overview.rst	New central overview of UTM concepts and feature groupings in Mautic.
docs/utm_tags/utm_tags_landing_pages.rst	New doc for inbound UTM capture via Landing Page visits/tracking script.
docs/utm_tags/utm_tags_asset_downloads.rst	New doc describing Asset download UTM behavior and limitations.
docs/utm_tags/utm_tags_forms.rst	New doc for capturing/storing UTMs via the “Record UTM tags” Form action.
docs/utm_tags/utm_tags_emails.rst	New doc for outbound UTM stamping on tracked Email links.
docs/utm_tags/utm_tags_dynamic_web_content.rst	New doc for outbound UTM stamping in Dynamic Web Content blocks.
docs/utm_tags/utm_tags_campaign_conditions.rst	New doc describing how to branch Campaign flow based on Contact UTM fields.
docs/utm_tags/utm_tags_segment_filters.rst	New doc describing Segment filtering using Contact UTM fields.
docs/index.rst	Moves UTM Tags into a dedicated docs section and adds new toctree entries.
docs/components/dynamic_web_content.rst	Updates the UTM docs link target for DWC docs.
docs/channels/focus_items.rst	Updates the UTM docs link target for Focus Items docs.
docs/channels/utm_tags.rst	Removes the old UTM Tags page (superseded by the new section).
.github/styles/config/vocabularies/Mautic/accept.txt	Adds CPC and DWC to accepted terminology for Vale.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

Suppressed comments (10)

docs/utm_tags/utm_tags_landing_pages.rst:16

• This section nests a second .. note:: inside another note, which is redundant and can render oddly in Sphinx. Use a single note block.

.. note::

   .. note::

   Landing Pages have no settings, fields, or toggles for UTM parameters. If asked where to configure UTM tags for a Landing Page, the answer is always in the link that brings visitors to the Landing Page.

docs/utm_tags/utm_tags_forms.rst:43

• The example uses utm_medium=Email, but later the doc explains utm_medium=email. UTM values are typically case-sensitive in analytics tooling, so the example should match the recommended lowercase value.

      https://example.com/landing-Page?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026

docs/utm_tags/utm_tags_forms.rst:61

• Avoid leaving TODO markers in merged docs. If a screenshot isn’t included in this PR, replace with a neutral comment (or remove) and track the screenshot separately.

.. TODO: add screenshot - Contact timeline showing a "UTM tags recorded" entry with populated UTM fields and a FORMID reference

docs/utm_tags/utm_tags_emails.rst:31

• This step refers to an “inside this block”, but the instructions are for an Email. This can confuse readers (blocks apply to DWC, not Emails).

#. Fill in the UTM fields you want to apply to links inside this block:

docs/utm_tags/utm_tags_emails.rst:44

• The example URL uses utm_medium=Email, but the surrounding text recommends utm_medium=email. Use the lowercase value for consistency and to avoid case-sensitive analytics mismatches.

      https://example.com/promo?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026

docs/utm_tags/utm_tags_asset_downloads.rst:21

• The example URL uses utm_medium=Email, but the description immediately below states utm_medium=email. Use lowercase in the example for consistency (and to match common analytics expectations).

   https://example.com/Asset/your-file?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026

docs/utm_tags/utm_tags_segment_filters.rst:40

• Inline literal for utm_content is missing a closing double-backtick, which breaks the RST inline-code formatting for this bullet.

   * ``utm_content`

docs/utm_tags/utm_tags_forms.rst:19

• Wording issue: “Open the Form and the edit details” is ungrammatical; it should be “edit its details”.

#. Open the Form and the edit details:

docs/utm_tags/utm_tags_emails.rst:23

• Wording issue: “Open the Email and the edit details” is ungrammatical; it should be “edit its details”.

This issue also appears on line 31 of the same file.

#. Open the Email and the edit details:

docs/utm_tags/utm_tags_overview.rst:145

• The API payload keys here use inconsistent casing (User_agent) and a different spelling than is commonly used for the HTTP header (referer). If the actual endpoint expects referer and user_agent (lowercase), this line will mislead API users; please align with the real request schema.

* ``POST /contacts/{id}/utm/add``: accepts the full UTM payload - all five tags, plus ``url``, ``referrer``, and ``User_agent``

[RCheesley]

@promptless-for-oss please also check this PR against our standards and suggest any improvements. Take into account any comments from Copilot, too.

[promptless-for-oss]

Sure @RCheesley — I'll review this PR against our documentation standards, work through Copilot's comments, and apply the improvements that make sense. I'll follow up here with a summary of what I changed and how I handled each Copilot point.

[promptless-for-oss]

Done — I've cherry-picked your small code-review tweaks from this PR across all four version backport PRs: 7.1 (#921), 7.2 (#922), 6.0 (#923), and 5.2 (#924). Each now uses example.com in the sample UTM URLs on the Forms and Landing Pages pages, matching your edit. The third file you touched here (the utm_content literal in the Segment filters page) already had that fix on the backports, so no change was needed there. Vale passes on all the changed files.

(Your other request — reviewing this PR against our standards and Copilot's comments — is still in progress; I'll follow up separately on that.)

[promptless-for-oss]

Thanks @RCheesley — I've reviewed this PR against our documentation standards and worked through all of Copilot's comments. Overall it's in good shape: Vale is clean (0 errors; the 2 remaining warnings are proper-noun false positives on headings containing 'Email' and 'Landing Pages'). Two of Copilot's flags are genuine accuracy bugs I confirmed against Mautic's 7.0 source. Here's the full disposition plus a few additional findings.

Copilot comments:

• ✅ Nested .. note:: inside a note (landing_pages.rst:12–16) — collapse to one note block.
• ✅ "UTM - Urchin Tracking Module - are" (overview.rst:6) — reword to "UTM tags - Urchin Tracking Module - are".
• ✅ DWC cross-ref says UTM applies to "links and Form submissions" (components/dynamic_web_content.rst:98) — the DWC page documents link tagging only; narrow to "links".
• ✅ utm_medium=Email → utm_medium=email in three example URLs (asset_downloads.rst:21, forms.rst:43, emails.rst:44) — each contradicts its own surrounding prose; analytics treats medium case-sensitively.
• ✅ "links inside this block" on an Email step (emails.rst:31) — change "block" → "Email".
• ✅ Missing closing backtick on utm_content (segment_filters.rst:40) — real RST render break.
• ✅ "Open the Form/Email and the edit details" (forms.rst:19, emails.rst:23) — "and edit its details".
• ✅ Accuracy (source-verified) — API payload keys (overview.rst:145): referrer → referer and User_agent → user_agent (Mautic's UtmTag::getFieldSetterList() uses lowercase user_agent, referer).
• ⏸️ Leftover .. TODO screenshot marker (forms.rst:61) — it's an RST comment that renders nothing, and issue [DOCS]: Add screenshot of contact activity feed with UTM tags #925 already tracks the screenshot; your call whether to drop the line now.
• ➖ utm_medium casing on landing_pages.rst:25 — already lowercase at head, no action.

Additional findings beyond Copilot:

• Same "and edit its details" grammar fix on dynamic_web_content.rst:19.
• Action-label casing: standardize to the product's actual label Record UTM Tags (capital T) at forms.rst:8 and :59, matching forms.rst:29 and asset_downloads.rst:50.
• campaign_conditions.rst:8 and :44 use single-quoted 'yes'/'no'/'No' path names; make them bold Yes/No to match line 34 and the bold-UI-label convention.
• emails.rst:8 mixes hosts in one sentence: normalize https://yoursite.com/promo → example.com (low priority).
• dynamic_web_content.rst:56 final sentence is missing its terminal period.

One heads-up on mechanics: because this PR's branch lives on Anderson's personal fork, Promptless can't push these edits into it directly — the same limitation Ayu hit earlier. So either the author/maintainer applies the list above manually, or I can open a fresh PR against 7.0 with all of these applied — just let me know which you'd prefer.