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 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]

Thanks @adiati98 — I've worked through all of GitHub Copilot's review suggestions on this PR. Since this is your and @andersonjeccel's PR (on the contributor's fork), I can't push onto the docs-for-utm-tags branch directly — per your earlier note that Promptless applies changes manually here. So here are the fixes, itemized for you to apply:

docs/utm_tags/utm_tags_landing_pages.rst — collapse the .. note:: that was nested inside another .. note:: into a single note block.

docs/utm_tags/utm_tags_segment_filters.rst — fix the malformed inline literal: utm_content` → ``utm_content`` `` (missing closing backtick).

Example URL casing — lowercase utm_medium=Email → utm_medium=email in the example URLs, so they match the recommended lowercase value in the surrounding text (case-sensitive in analytics tooling). Affects utm_tags_asset_downloads.rst, utm_tags_forms.rst, and utm_tags_emails.rst.

Grammar — docs/utm_tags/utm_tags_forms.rst and utm_tags_emails.rst: "Open the Form/Email and the edit details" → "Open the Form/Email and edit its details".

docs/utm_tags/utm_tags_emails.rst — change "links inside this block" to "links in the Email" (the "block" phrasing applies to Dynamic Web Content, not Emails).

docs/utm_tags/utm_tags_overview.rst (intro) — fix the singular/plural agreement in the opening sentence.

docs/utm_tags/utm_tags_overview.rst (REST API bullet) — Copilot flagged the payload key casing. I verified the real request schema against the Mautic source (UtmTag::getFieldSetterList): the endpoint's accepted keys are referer (single "r", matching the HTTP Referer header) and user_agent (lowercase). So referrer / User_agent were both corrected, with a short note added so the single-r spelling isn't mistaken for a typo.

docs/components/dynamic_web_content.rst — narrowed the UTM description to link tagging only.

Separately, on your request to add the timeline screenshot (issue #925): that's captured (against Mautic 7.0.2) and included with these changes in utm_tags_forms.rst.

Vale passes on every changed file. All of the above is staged together on our side and ready to copy into this PR — happy to hand it over in whatever form is easiest for you; just let me know.

[adiati98]

@adiati98 No — merging this PR only merges its own head branch (docs-for-utm-tags) into 7.0. promptless/utm-tags-712-screenshot-requirements is a separate branch with no PR of its own; it's just built on top of this PR's commits so the screenshot + fixes apply cleanly. Merging #712 won't bring it in.

To include our changes, either apply that 6-file delta onto this PR's branch before merging (the incremental diff is git diff 0b6de56c..7a2e61cb), or merge #712 first and we can open a follow-up PR against 7.0 with just those changes. Happy to do whichever you prefer.

@promptless-for-oss open a follow-up PR against 7.0 just with the changes. Apply these changes directly in other PRs.

[promptless-for-oss]

On it, @adiati98 👍 We'll open a follow-up PR against 7.0 with just these changes (the Contact-timeline screenshot plus the review/Copilot nits), and apply the same edits directly across the other version PRs (#921, #922, #923, #924). I'll follow up here with a per-target rundown once they're in.

[promptless-for-oss]

Quick update: we've reconciled the staged changes against the current state of this PR and the four version PRs. Several of the review nits are already applied here directly (the utm_content backtick, the collapsed nested note, the API payload key casing, and a few wording/host fixes) — thanks for that. What's still outstanding narrows to: the Contact-timeline screenshot (tracked by #925), the utm_medium=Email→email fix in three example URLs, the Record UTM Tags label casing, bold Yes/No in the campaign conditions page, and a couple of small grammar/punctuation nits. Preparing the follow-up 7.0 PR and syncing these across #921/#922/#923/#924 now — full rundown to follow.

[adiati98]

@promptless-for-oss please cherry pick the newest commit in other PRs.

[promptless-for-oss]

The follow-up PR against 7.0 is up: #965. It carries the Contact-timeline screenshot plus the outstanding review/Copilot nits (the utm_medium=Email→email fix, Record UTM Tags label casing, bold Yes/No in campaign conditions, and a couple of grammar/punctuation fixes). It's stacked on this PR's head, so its diff currently shows #712's commits too and collapses to just the 6-file change once #712 merges — the PR body notes this and offers to apply the changes directly onto #712's branch instead if you'd rather.

Two items I left for you to decide rather than applying silently (both flagged in #965's description): the Yes/No condition-path labels (7.x source distinguishes those paths by green/red color — happy to switch if you prefer that terminology), and a small wording tidy.

And yes — on your cherry-pick request, I'm syncing #712's newest commit (the batched code-review suggestions) into #921/#922/#923/#924 now, along with the rest of the outstanding fixes. Per-PR rundown to follow.

[promptless-for-oss]

Both requests are done, @adiati98 👍

Follow-up PR against 7.0: #965 — carries just the outstanding changes for #712: the 'UTM tags recorded' Contact-timeline screenshot (issue #925), the Record UTM Tags action-label casing, lowercase utm_medium=email in the three example URLs, a missing terminal period, and a couple of small grammar fixes. It's built on top of #712's current head, so its diff currently shows #712's commits too and collapses to just the 6-file change once #712 merges. If you'd rather, we can apply these straight onto #712's branch instead — just say the word.

Cherry-pick synced into the four backports: each now matches #712's current head — including your latest batched code-review commit — plus the same outstanding fixes above:

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

The 6.0 and 5.2 PRs keep their own Google-Analytics screenshot filename (add_ga_code.png) as-is; the new timeline screenshot uses the same filename on every branch.

Two judgment calls flagged (not applied blindly) in each PR description for you to decide:

• The Yes/No Campaign-condition path labels — we bolded them for within-page consistency, but 7.x actually distinguishes those paths by green/red color rather than literal 'Yes'/'No' text. Happy to switch to that wording if you prefer.
• A small grammar tidy — removing a redundant "the" from the "Open the … and edit its details" steps (your "its" wording kept).

Vale is clean on all changed lines across every PR. Just let us know your call on the two flagged items and whether you'd like #965 applied directly onto #712's branch.

[adiati98]

Two judgment calls flagged (not applied blindly) in each PR description for you to decide:

• The Yes/No Campaign-condition path labels — we bolded them for within-page consistency, but 7.x actually distinguishes those paths by green/red color rather than literal 'Yes'/'No' text. Happy to switch to that wording if you prefer.
• A small grammar tidy — removing a redundant "the" from the "Open the … and edit its details" steps (your "its" wording kept).

@promptless-for-oss answering your questions in the quote above:

• We must follow the UI. So, if the UI uses green/red color, we should follow. Please switch to that wording. You need to investigate the other branches, too, and update accordingly, following their UI.
• I agree with tidying the small grammar enhancement. Apply this to other PRs, too.

[promptless-for-oss]

Thanks @adiati98 — got it, and we're on both:

• Yes/No Campaign-condition labels: we'll switch to the green/red color wording, verifying against the actual UI on each version and updating the 7.0 follow-up (Add UTM timeline screenshot and resolve outstanding review nits (follow-up to #712) #965) plus the parallel PRs (Comprehensive UTM tags documentation (backport of #712 to 7.1) #921, Comprehensive UTM tags documentation (backport of #712 to 7.2) #922, Comprehensive UTM tags documentation (backport of #712 to 6.0) #923, Comprehensive UTM tags documentation (backport of #712 to 5.2) #924) to match what each branch's UI shows.
• Grammar tidy: we'll keep the redundant-"the" removal and apply it across the other PRs too.

We'll follow up here with a per-target rundown once the changes are in.

[promptless-for-oss]

Update: we've verified the Campaign-condition paths against the actual UI on every version (5.2 through 7.2) — all render the same, a green path for the match and a red path for the no-match, with no literal Yes/No text (matching the existing campaign builder docs). So the fix is consistent across branches: swapping the bold Yes/No for the green/red path wording. The grammar tidy is already in place on all five PR heads. Applying the label wording change across #965, #921, #922, #923, and #924 now.

[promptless-for-oss]

Both of your calls on the UTM tags docs are done across all five PRs — #965 (7.0 follow-up), #921 (7.1), #922 (7.2), #923 (6.0), and #924 (5.2).

Yes/No condition-path labels: we checked the Campaign Builder UI against the Mautic source on every version you asked about (5.2, 6.0, 7.0, 7.1, 7.2) and it's the same everywhere — the Contact field value condition node shows a green connector for the match path and a red connector for the no-match path, with no literal 'Yes'/'No' text. So we switched all five pages to the green/red path wording, which also matches how campaign_builder.rst already describes condition paths ('two paths, denoted by red and green icons'). There was no version-to-version UI difference to account for.

Grammar tidy: the redundant 'the' was already removed on every branch (the steps read 'Open the … and edit its details'), so no further change was needed there.

Each edits the single docs/utm_tags/utm_tags_campaign_conditions.rst page, Vale is clean, and every PR description now marks both items resolved.

[adiati98]

@promptless-for-oss please create PRs to cherry-pick the changes here for 7.3 and 8.0 branches.

[promptless-for-oss]

Thanks @adiati98 — Promptless is preparing PRs to cherry-pick the UTM tags documentation changes from this PR onto the 7.3 and 8.0 branches. We'll follow up here with the PR links once they're up.

[promptless-for-oss]

Thanks @adiati98 — both cherry-picks are done. I've opened two draft PRs porting #712's UTM tags changes:

• 7.3: Comprehensive UTM tags documentation (backport of #712 to 7.3) #996
• 8.0: Comprehensive UTM tags documentation (backport of #712 to 8.0) #997

The full restructure applied cleanly to both branches via 3-way merge (13 files, +586/−94, no conflicts) — the new eight-page docs/utm_tags/ section, the index toctree caption, the repointed Focus Items and Dynamic Web Content links, removal of the old docs/channels/utm_tags.rst, and the CPC/DWC Vale vocabulary additions. Both mirror #712's current head verbatim, and Vale is clean on all ported lines.

Two things I deliberately carried over verbatim from #712 rather than normalizing, in case you'd like a follow-up on both branches:

• Both retain EVERYTHING about UTM tags in Mautic #712's .. TODO placeholder for the 'UTM tags recorded' timeline screenshot on the Forms page. Once EVERYTHING about UTM tags in Mautic #712 resolves that screenshot, the same follow-up would apply to 7.3/8.0.
• The example URLs keep EVERYTHING about UTM tags in Mautic #712's utm_medium=Email and landing-Page casing (inside code blocks, so not Vale-flagged). The earlier 7.2 backport lowercased these for consistency; I left them matching EVERYTHING about UTM tags in Mautic #712's current head, so let me know if you'd like them lowercased here too.

[RCheesley]

I think that these PRs are good to go now but will leave it for Ayu to push the button!