EVERYTHING about UTM tags in Mautic

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 any links and Form submissions. See :doc:`/utm_tags/utm_tags_overview` for more information.
 
 .. vale off
 

docs/index.rst

@@ -115,7 +115,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
@@ -222,6 +221,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,47 @@
+.. 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 Pages. Understanding the distinction prevents tracking gaps and misplaced expectations.
+
+How asset download UTM works
+*****************************
+
+UTM values on Asset downloads are only populated when the Asset URL is shared 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://your-mautic.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.
+
+Those values store on the **download record itself**, not on the Contact's profile. This distinction matters because it restricts how you can use the data downstream:
+
+- The UTM values are available for **Asset Reports only**.
+- They don't appear on the Contact's activity timeline.
+- They can't use in Segment filters based on Contact UTM data.
+
+Limitation: form-triggered downloads
+**************************************
+
+A common way Contacts download Assets in is through a Form action ("Download Asset") on submit. In this flow, UTM parameters are never captured, not because of a configuration issue, but because of how generates the download URL internally:
+
+.. code-block:: text
+
+   https://your-mautic.com/Asset/some-uuid?ct=eyJsZWFkIjoxMjMsImNoYW5uZWwiOnsiZm9ybSI6NH19&stream=0
+
+generates this URL internally at the moment of Form submission. The token-based ``ct`` parameter carries identity and Channel context, but the original Page URL's UTM parameters, for example ``utm_source=newsletter``, are never forwarded 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 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 Page URL, there's no mechanism to pass the 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 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,48 @@
+.. 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. This is complete through a **Contact field value** condition node, which has a dedicated UTM Tags section that exposes all five standard UTM fields. Depending on whether the Contact's UTM data matches your condition, the Campaign routes them down the "yes" or "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 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 you want to configure by going to **Campaigns** and clicking the Campaign name, then opening the Campaign builder.
+
+#. Add a condition node by clicking the **+** on your Campaign flow and selecting **Condition** > **Contact field value**.
+
+#. In the condition editor, scroll down to the **UTM tags** section. You sees all five UTM fields listed:
+
+   - ``Source``
+   - ``Medium``
+   - ``Campaign``
+   - ``Content``
+   - ``Term``
+
+#. Select the field you want to evaluate and enter the value to match, set ``Medium`` to ``email``, or ``Campaign`` to ``spring_sale_2026``.
+
+#. Connect the condition node's **Yes** and **No** paths to the appropriate next steps in the Campaign flow.
+
+#. Save the Campaign and activate it.
+
+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 you want to unify follow-up logic across several Campaigns that all used the same Channel. Branching on ``utm_campaign`` is better when you need Campaign-specific personalization in your messaging. Both approaches are valid, the right choice depends on how granular your segmentation needs to be.
+
+.. warning::
+
+   The UTM condition evaluates the values **currently recorded** on the Contact's profile at the moment the Campaign processes them. If UTM data hasn't capture yet when the Contact enters the Campaign, for example, they entered before submitting the Form that records UTM tags, the condition evaluates against empty values and routes them to the "No" path. Order matters.
+
+Contacts with matching UTM values should route to the "Yes" path once the Campaign processes them.
+
+.. 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,53 @@
+.. vale off
+
+UTM tags in Dynamic Web Content blocks
+########################################
+
+.. vale on
+
+When you add UTM fields to a Dynamic Web Content (Dynamic Web Content (DWC)) block in Mautic, you aren't filtering which Contacts see the block, you are tagging the outbound links inside it. Every trackable link in the Dynamic Web Content (DWC) content automatically has your UTM parameters appended to it when the block renders on the Page.
+
+This means you can track in Google Analytics, or any other analytics tool, exactly how many people clicked links coming from that specific Dynamic Web Content (DWC) block, without manually editing each URL in your content. To use this, you need permission to edit Dynamic Web Content in Mautic, a Dynamic Web Content (DWC) block with at least one outbound link, and an analytics tool set up on the destination website to receive UTM-tagged traffic.
+
+Configure DWC blocks
+********************
+
+#. Open the Dynamic Web Content block you want to configure by going to **Components** > **Dynamic Web Content** and clicking the block name.
+
+#. Locate the UTM fields in the block settings. These are separate from the content body and the Segment or filter conditions.
+
+#. Fill in the UTM fields you want to apply to links inside this block:
+
+   - ``Campaign``, the Campaign name, ``spring_sale_2026``
+   - ``Medium``, the Channel type, ``website``
+   - ``Source``, where the block is placed, ``dwc``
+   - ``Content`` is optional, use it if you need finer-grained tracking
+
+#. Save the Dynamic Web Content (DWC) block.
+
+#. Embed the block on the website.
+
+#. Test by visiting the Page as an anonymous visitor, hovering over or clicking a link inside the Dynamic Web Content (DWC) block, and confirming the destination URL now includes your UTM parameters, for example:
+
+   .. code-block:: text
+
+      https://yoursite.com/landing?utm_campaign=spring_sale_2026&utm_medium=website&utm_source=dwc
+
+This URL was produced by a Dynamic Web Content (DWC) block configured with ``utm_campaign=spring_sale_2026``, ``utm_medium=website``, and ``utm_source=dwc``. The ``utm_source`` value ``dwc`` is a short, descriptive token that makes it immediately clear in analytics Reports that the traffic originated from a Dynamic Web Content block rather than an Email, paid ad, or other Channel.
+
+The ``utm_medium=website`` value reflects that the block renders on a website Page rather than inside an Email. Keeping the medium accurate allows your analytics tool to correctly classify this traffic in its Channel groupings. The ``utm_campaign`` value ties this block's traffic to the same named Campaign you use in your Emails and ads, so all Campaign-level traffic aggregates cleanly under one name in your Reports.
+
+.. warning::
+
+   If a link in your Dynamic Web Content (DWC) content already has UTM parameters hard-coded in it, Mautic may append a second set, resulting in a malformed URL. Keep links in Dynamic Web Content (DWC) content clean, no manual UTM parameters, and let the block-level fields do the tagging.
+
+.. tip::
+
+   Use consistent naming across blocks. If one block uses ``source=dwc`` and another uses ``source=dynamic-web-content``, your analytics data is/are split across two rows and harder to compare.
+
+When the setup is working correctly, links inside the Dynamic Web Content (DWC) block include UTM parameters when rendered on the Page, clicking through and checking the destination URL in the browser address bar shows the correct parameters, and traffic from that block appears as a distinct source/medium combination in Google Analytics.
+
+.. seealso::
+
+   - :doc:`utm_tags_overview`
+   - :doc:`utm_tags_emails`

docs/utm_tags/utm_tags_emails.rst

@@ -0,0 +1,51 @@
+.. vale off
+
+UTM tags in email
+##################
+
+.. vale on
+
+Every trackable link inside the Email body have your UTM parameters automatically appended when the Email send or previewed. This means a clean link like ``https://yoursite.com/promo`` in your Email becomes ``https://yoursite.com/promo?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale_2026`` in the recipient's inbox. Google Analytics, or any analytics tool, then attributes those visits to that specific Email send, letting you measure click-through traffic per Campaign without touching individual links in the content.
+
+To use this, you need permission to edit Emails in Mautic, at least one outbound link in the Email body, and an analytics tool set up on the destination website to receive UTM-tagged traffic.
+
+.. tip::
+
+   Use the same ``Campaign`` value across your Email, Dynamic Web Content (DWC) blocks, and any paid ads running at the same time. All traffic from a single Campaign then rolls up cleanly under one Campaign name in Analytics, regardless of which Channel drove the click.
+
+Configure email UTM tags
+************************
+
+#. Open the Email you want to configure by going to **Channels** > **Emails** and clicking the Email name.
+
+#. Locate the UTM fields in the Email settings. These are separate from the Email body content.
+
+#. Fill in the four available UTM fields:
+
+   - ``Source``, where the Email is coming from, ``newsletter`` or ``mautic``
+   - ``Medium``, the Channel, ``email``
+   - ``Campaign``, the Campaign name, ``spring_sale_2026``
+   - ``Content``, optional. useful for distinguishing between multiple Emails in the same Campaign, ``welcome_email_1``
+
+#. Save the Email.
+
+#. Test by using the Email preview or sending a test to yourself, then hovering over a link in the Email and confirming the destination URL includes your UTM parameters, for example:
+
+   .. code-block:: text
+
+      https://yoursite.com/promo?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026
+
+This URL results from an Email configured with ``utm_source=newsletter``, ``utm_medium=email``, and ``utm_campaign=spring_sale_2026``. The ``utm_source`` value ``newsletter`` clearly identifies the sending list or newsletter program as the origin. The ``utm_medium`` value ``email`` tells analytics tools to classify this traffic in the Email Channel grouping. The ``utm_campaign`` value ties the click to the named marketing initiative.
+
+Setting ``utm_medium=email`` is important for Channel attribution accuracy. If you omit this field or set an incorrect value, your analytics tool may misclassify the traffic, for instance, attributing it to direct or referral traffic rather than Email. The ``utm_content`` field becomes valuable when you send multiple Emails within the same Campaign. it lets you compare performance between, say, ``welcome_email_1`` and ``welcome_email_2`` while keeping both associated with the same Campaign name.
+
+When the setup is correct, links in the Email preview and test send include the configured UTM parameters, clicking through from a test Email shows the UTM values in the browser address bar on the destination Page, and after a real send, traffic appears as a distinct source/medium combination in Google Analytics.
+
+.. warning::
+
+   If links in your Email body already have UTM parameters hard-coded, Mautic may stack a second set on top, leading to duplicate or malformed parameters. Keep links in the Email body clean, no manual UTM parameters, and let the Email-level fields do the tagging.
+
+.. seealso::
+
+   - :doc:`utm_tags_overview`
+   - :doc:`utm_tags_dynamic_web_content`