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

.github/styles/config/vocabularies/Mautic/accept.txt

@@ -29,6 +29,7 @@ ConnectWise
 Contribution(s)
 CORS
 cPanel
+CPC
 CRM
 cron
 Cron
@@ -39,6 +40,7 @@ Do Not Contact
 DNC
 Dripflow
 DSN
+DWC
 Dynamic Web Content
 FALSE
 Focus Item

docs/channels/focus_items.rst

@@ -164,7 +164,7 @@ When creating a new Focus Item, you can set the following fields:
 
 .. vale on
 
-**Google Analytics UTM tags** - Mautic supports UTM tagging in Emails, Focus Items, and Landing Pages. Any UTM tags with values populated are automatically appended to the end of any links used in the Focus Item. See :doc:`/channels/utm_tags` for more information.
+**Google Analytics UTM tags** - Mautic supports UTM tagging in Emails, Focus Items, and Landing Pages. Any UTM tags with values populated are automatically appended to the end of any links used in the Focus Item. See :doc:`/utm_tags/utm_tags_overview` for more information.
 
   .. image:: images/focus_items/focus_item_create.png
     :width: 400

docs/components/dynamic_web_content.rst

@@ -95,7 +95,7 @@ The following values are available:
 
 .. vale on
 
-**UTM tags** - Mautic can append UTM tags to any links and Form submissions. See :doc:`/channels/utm_tags` for more information.
+**UTM tags** - Mautic can append UTM tags to tracked links in Dynamic Web Content. See :doc:`/utm_tags/utm_tags_overview` for more information.
 
 .. vale off
 

docs/index.rst

@@ -116,7 +116,6 @@ There are different types of documentation available to help you navigate your w
    channels/social_monitoring
    channels/web_notifications
    channels/push_notifications
-   channels/utm_tags
 
 .. toctree::
    :maxdepth: 2
@@ -223,6 +222,20 @@ There are different types of documentation available to help you navigate your w
 
    stages/stages
 
+.. toctree::
+   :maxdepth: 2
+   :caption: UTM Tags
+   :hidden:
+
+   utm_tags/utm_tags_overview
+   utm_tags/utm_tags_landing_pages
+   utm_tags/utm_tags_asset_downloads
+   utm_tags/utm_tags_forms
+   utm_tags/utm_tags_emails
+   utm_tags/utm_tags_dynamic_web_content
+   utm_tags/utm_tags_campaign_conditions
+   utm_tags/utm_tags_segment_filters
+
 .. toctree::
    :maxdepth: 2
    :caption: Themes

docs/utm_tags/utm_tags_asset_downloads.rst

@@ -0,0 +1,59 @@
+.. vale off
+
+UTM tags on Asset downloads
+###########################
+
+.. vale on
+
+Mautic can capture UTM parameters when a Contact downloads a managed Asset, a file hosted inside Mautic. However, this behavior differs significantly from UTM capture on Forms, Emails, Dynamic Web Content - DWC - blocks, and Landing Pages. Understanding the distinction prevents tracking gaps and misplaced expectations.
+
+.. vale off
+
+How Asset download UTM works
+****************************
+
+.. vale on
+
+Mautic only populates UTM values on Asset downloads when you share the Asset URL directly as a link with UTM parameters manually included, for example, inside an Email, a button, or any other Channel where you control the full URL:
+
+.. code-block:: text
+
+   https://example.com/asset/your-file?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale_2026
+
+In this URL, ``utm_source=newsletter`` identifies the sending newsletter as the origin, ``utm_medium=email`` identifies the Channel, and ``utm_campaign=spring_sale_2026`` groups the download under a named Campaign. You construct this URL manually and place it directly in your content rather than relying on a Form submit action.
+
+Mautic stores those values on the **download record itself**, not on the Contact's profile. This distinction matters because it restricts how you can use the data downstream:
+
+* You can only view UTM values in **Asset Reports**.
+* You won't see them on the Contact's activity timeline.
+* You can't use them in Segment filters based on Contact UTM data.
+
+.. vale off
+
+Limitation: Form-triggered downloads
+************************************
+
+.. vale on
+
+.. vale off
+
+Contacts commonly download Assets through the **Download an asset** Form action on submit. In this flow, Mautic never captures UTM parameters, not because of a configuration issue, but because of how Mautic generates the download URL internally:
+
+.. vale on
+
+.. code-block:: text
+
+   https://example.com/asset/some-uuid?ct=eyJsZWFkIjoxMjMsImNoYW5uZWwiOnsiZm9ybSI6NH19&stream=0
+
+Mautic generates this URL internally at the moment of Form submission. The token-based ``ct`` parameter carries identity and Channel context, but Mautic never forwards the original Landing Page URL's UTM parameters, for example ``utm_source=newsletter``, to that download request. As a result, the UTM fields on every Form-triggered download record are always empty.
+
+This internal URL format reflects how Mautic tracks Asset delivery through its own Contact tracking layer rather than through query string parameters. Because the download request originates from Mautic's backend rather than from the visitor's browser carrying the original Landing Page URL, there's no mechanism to pass the Landing Page-level UTM context forward to the Asset download record.
+
+.. important::
+
+   If you need UTM data to appear on the Contact's profile for segmentation or timeline visibility, use the **Record UTM Tags** Form action instead. That action reads UTM parameters from the Landing Page URL at submission time and writes them to the Contact's profile. See :doc:`utm_tags_forms` for setup instructions.
+
+.. seealso::
+
+   * :doc:`utm_tags_overview`
+   * :doc:`utm_tags_forms`

docs/utm_tags/utm_tags_campaign_conditions.rst

@@ -0,0 +1,51 @@
+.. vale off
+
+UTM tags as Campaign conditions
+###############################
+
+.. vale on
+
+Inside a Mautic Campaign, you can branch the flow based on the UTM values recorded on a Contact's profile. You complete this through a **Contact field value** condition, whose **Contact Field** dropdown includes a **UTM** group with all five standard UTM fields. Depending on whether the Contact's UTM data matches your condition, the Campaign routes them down the green 'yes' path or the red 'no' path, letting you deliver different follow-up actions, Emails, or wait steps based on where the Contact originally came from.
+
+For this to work, Contacts must already have UTM data on their profile, captured via a Form submission with the **Record UTM Tags** action or via a Landing Page visit with UTM parameters in the URL. The Campaign must also have a trigger - Segment membership, Form submission, or similar - configured before adding condition nodes.
+
+Configure conditions
+********************
+
+#. Open the Campaign and launch the Campaign Builder:
+
+   #. Go to **Campaigns**.
+   #. Click the name of the Campaign to modify.
+   #. Click **Edit**.
+   #. Click **Launch Campaign Builder**.
+
+#. Add a condition node by clicking the **+** on your Campaign flow and selecting **Condition** > **Contact field value**.
+
+#. In the **Contact Field** dropdown, scroll to the **UTM** group to view all five available UTM fields:
+
+   * **Campaign**
+   * **Content**
+   * **Medium**
+   * **Source**
+   * **Term**
+
+#. Select the field you want to evaluate and enter the value to match. For example, set **Medium** to ``email``, or **Campaign** to ``spring_sale_2026``.
+
+#. Connect the condition's green 'yes' path and red 'no' path to the appropriate next steps in the Campaign flow.
+
+#. Save and activate the Campaign.
+
+The preceding example uses **Medium** checked against ``email`` as the evaluated field, which correctly identifies Contacts who arrived through an Email Channel before entering this Campaign. Alternatively, checking **Campaign** against ``spring_sale_2026`` lets you deliver Campaign-specific messaging to Contacts acquired through that Campaign while routing Contacts from other Campaigns to a different path.
+
+Branching on ``utm_medium`` rather than ``utm_campaign`` is useful when unifying follow-up logic across several Campaigns that all used the same Channel. Branching on ``utm_campaign`` works better when requiring Campaign-specific personalization in messaging. Both approaches are valid depending on how granular your segmentation needs to be.
+
+.. warning::
+
+   The UTM condition evaluates the values **currently recorded** on the Contact profile at the moment the Campaign processes them. If Mautic hasn't captured UTM data when the Contact enters the Campaign - for example, if they entered before submitting the Form that records UTM tags - the condition evaluates against empty values and routes the Contact to the red 'no' path. Order matters.
+
+.. seealso::
+
+   * :doc:`utm_tags_overview`
+   * :doc:`utm_tags_forms`
+   * :doc:`utm_tags_segment_filters`
+   * :doc:`/campaigns/campaign_builder`

docs/utm_tags/utm_tags_dynamic_web_content.rst

@@ -0,0 +1,61 @@
+.. vale off
+
+UTM tags in Dynamic Web Content blocks
+######################################
+
+.. vale on
+
+When you add UTM fields to a Dynamic Web Content - DWC - block in Mautic, you aren't filtering which Contacts see the block. Instead, you are tagging the outbound links inside it. Mautic automatically appends your UTM parameters to every trackable link in the DWC content when the block renders on the Landing Page.
+
+This enables you to track in Google Analytics, or any other analytics tool, exactly how many people clicked links coming from that specific DWC block, without manually editing each URL in your content. To use this, you need permission to edit Dynamic Content in Mautic, a DWC block with at least one outbound link, and an analytics tool set up on the destination website to receive UTM-tagged traffic.
+
+.. vale off
+
+Configure DWC blocks
+********************
+
+.. vale on
+
+#. Open the DWC block to start editing:
+
+   #. Go to **Components** > **Dynamic Content**.
+   #. Click the name of the DWC block you want to modify.
+   #. Click **Edit**.
+
+#. Locate the **UTM tags** dropdown menu in the right-hand panel at the bottom. Expanding this section exposes the UTM parameter fields, which sit separately from the content body and filter conditions.
+
+#. Fill in the UTM fields you want to apply to links inside this block:
+
+   * **Campaign source**: where you place the block, for example, ``dwc``
+   * **Campaign medium**: the Channel type, for example, ``website``
+   * **Campaign name**: the Campaign name, for example, ``spring_sale_2026``
+   * **Campaign content**: optional field for finer-grained tracking
+
+#. Save the DWC block.
+
+#. Embed the block on your website.
+
+#. Test by visiting the Landing Page as an anonymous visitor, hovering over or clicking a link inside the DWC block, and confirming the destination URL now includes your UTM parameters, for example:
+
+   .. code-block:: text
+
+      https://example.com/landing?utm_campaign=spring_sale_2026&utm_medium=website&utm_source=dwc
+
+A DWC block configured with ``utm_campaign=spring_sale_2026``, ``utm_medium=website``, and ``utm_source=dwc`` produces this URL. The ``utm_source`` value ``dwc`` is a short, descriptive token that makes it immediately clear in analytics Reports that traffic originated from a DWC block rather than an Email, paid ad, or other Channel.
+
+The ``utm_medium=website`` value reflects that the block renders on a website Landing Page rather than inside an Email. Keeping the medium accurate allows your analytics tool to classify traffic into the correct Channels. The ``utm_campaign`` value ties this block's traffic to the same named Campaign you use in Emails and ads, aggregating all Campaign-level traffic under one name in your Reports.
+
+.. warning::
+
+   If a link in your DWC content already contains hard-coded UTM parameters, Mautic may append a second set, resulting in a malformed URL. Keep links in DWC content clean without manual UTM parameters, and let block-level fields handle tagging.
+
+.. tip::
+
+   Use consistent naming across blocks. If one block uses ``source=dwc`` and another uses ``source=dynamic-web-content``, your analytics data splits across two rows, making comparison difficult.
+
+When the setup is working correctly, links inside the DWC block include UTM parameters when rendered on the Landing Page. Clicking through and checking the destination URL in the browser address bar shows the correct parameters. Traffic from that block appears as a distinct source or medium combination in your analytics platform.
+
+.. seealso::
+
+   * :doc:`utm_tags_overview`
+   * :doc:`utm_tags_emails`