diff --git a/docs/channels/focus_items.rst b/docs/channels/focus_items.rst index bbec54b5a..3bda718f7 100644 --- a/docs/channels/focus_items.rst +++ b/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 diff --git a/docs/channels/utm_tags.rst b/docs/channels/utm_tags.rst deleted file mode 100644 index 06667d054..000000000 --- a/docs/channels/utm_tags.rst +++ /dev/null @@ -1,91 +0,0 @@ -UTM tags -######## - -UTM tags are also known as parameters or short text codes. When adding these tags to URLs or links, marketers can track performance, create customised audiences, and analyze on website traffic from various sources. Marketers can also use UTM tags with Google Analytics to clearly understand the effectiveness of their marketing content and return on investment for marketing projects. - -Key benefits of using UTM tags -****************************** - -With UTM tags, you can: - -- Track the value of marketing projects and measure return on investment -- Get precise data about conversion and traffic sources -- Test the effectiveness of marketing content through A/B testing - -Using UTM tags in Mautic -************************ - -To use UTM tags with Google Analytics where they appear in your Google Analytics Dashboard, you must install your Google Analytics tracking code on the resource you are linking to. This synchronizes with your Google Analytics Dashboard and records the UTM tags. - -If you use a Mautic Landing Page, you must go to Settings > Configuration > Tracking Settings, and add your Google Analytics ID. - - .. image:: images/utm_tags/add_google_analytics_id.png - :alt: Screenshot showing the option to add your Google Analytics ID - -If you use a non-Mautic Landing Page, you must manually embed the Google Analytics tracking script on the third-party Page. - -Mautic Users can automatically append UTM tags to all links in an Email or Focus Item. For other Channels, you can make the link trackable by including UTM values in the URL address. When a Contact clicks a link in an Email or Focus Item, Mautic records UTM tags and stores them in the Contact record. You can find the details on the Contact Event History overview. After recording the UTM tags, you can use them as filters in Segments. - -You can use UTM tags to track Contacts who convert from Dynamic Web Content slots in Emails, and determine the source in Google Analytics or Mautic Reports. You can also use them as columns in a Report by selecting UTM codes as the data source. - -The following table lists the Google Analytics UTM tags: - -.. list-table:: Title - :widths: 50 50 - :header-rows: 1 - - * - UTM tags - - Description - * - Campaign Source - - The referring source of the web activity. It indicates the social network, search engine, newsletter name, or any other specific source driving the traffic. - * Examples: ``facebook``, ``twitter``, ``blog``, ``newsletters`` - * UTM code: ``utm_source`` - * Sample code: ``utm_source=facebook`` - * - Campaign Medium - - UTM tags - Mautic Documentation - * Examples: ``cpc``, ``organic_social`` - * UTM code: ``utm_medium`` - * Sample code: ``utm_medium=paid_social`` - * - Campaign Name - - The specific promotion or Campaign title that you want to track. - * Examples: ``summer_sale``, ``free_trial`` - * UTM code: ``utm_campaign`` - * Sample code: ``utm_campaign=summer_sale`` - * - Campaign Content - - The Assets within the messages. This non-configurable value auto-populates with the content Asset identifier associated with the specific Asset. - * - Campaign Term - - The keyword to search a Campaign. This non-configurable value auto-populates within the link text and tracks links within the messages. - -.. note:: - You don't need to fill all the options. You can use one, or a few, or all of them, as required. - -.. vale off - -Using UTM tags in Emails -************************ - -.. vale on - -Mautic supports UTM tagging in Emails. Mautic can automatically append UTM tags to all links in an Email by entering the appropriate Campaign values in the fields provided. - -#. In Mautic, click Channels > Emails. -#. Create a new Email or edit an existing Email. If you choose to edit an existing Email, click the Email and then click Edit. -#. Locate the Google Analytics UTM tags section on the bottom right. -#. Enter the appropriate information in the fields. -#. Click Apply. - -.. warning:: - * When adding links in Emails, use the edit link icon in the builder. - * When adding links in Code Mode, use the tag. - * All links must include a trailing slash. Otherwise, UTM codes aren't appended. - -Using UTM tags in Focus Items -***************************** - -Mautic supports UTM tagging in :doc:`/channels/focus_items`. Mautic can automatically append UTM tags to all links in a Focus Item by entering the appropriate values in the field provided. - -#. Click Channels > Focus Items -#. Create a new Focus Item or open an existing one. -#. Locate the Google Analytics UTM tags section on the bottom right. -#. Enter the appropriate information in the fields. -#. Click Apply. \ No newline at end of file diff --git a/docs/components/dynamic_web_content.rst b/docs/components/dynamic_web_content.rst index 4307b08c0..f200f83d1 100644 --- a/docs/components/dynamic_web_content.rst +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index df81ac676..7f9ca1260 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/utm_tags/utm_tags_asset_downloads.rst b/docs/utm_tags/utm_tags_asset_downloads.rst new file mode 100644 index 000000000..bf26c8b16 --- /dev/null +++ b/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` diff --git a/docs/utm_tags/utm_tags_campaign_conditions.rst b/docs/utm_tags/utm_tags_campaign_conditions.rst new file mode 100644 index 000000000..f75be68e5 --- /dev/null +++ b/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` diff --git a/docs/utm_tags/utm_tags_dynamic_web_content.rst b/docs/utm_tags/utm_tags_dynamic_web_content.rst new file mode 100644 index 000000000..c19ce36fd --- /dev/null +++ b/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` diff --git a/docs/utm_tags/utm_tags_emails.rst b/docs/utm_tags/utm_tags_emails.rst new file mode 100644 index 000000000..f644d6822 --- /dev/null +++ b/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` diff --git a/docs/utm_tags/utm_tags_forms.rst b/docs/utm_tags/utm_tags_forms.rst new file mode 100644 index 000000000..dc27f681b --- /dev/null +++ b/docs/utm_tags/utm_tags_forms.rst @@ -0,0 +1,60 @@ +.. vale off + +Recording UTM tags in Forms +############################ + +.. vale on + +When a Contact submits a Mautic Form, you can automatically capture the UTM parameters from the Page URL and store them on their profile. This handles this by a built-in Mautic action called **Record UTM tags**, but the action itself doesn't define which UTM values to capture. It reads whatever UTM parameters are already present in the URL of the Page where the Form lives. + +That means the website is responsible for ensuring UTM parameters include in the Landing Page URL, picks them up at submission time. The five standard parameters it captures are ``utm_source``, ``utm_medium``, ``utm_campaign``, ``utm_content``, and ``utm_term``. To follow the steps below, you need permission to edit Forms in Mautic and a Form already embedded on a website Page where the site sends UTM-tagged traffic. + +Add UTM recording +***************** + +#. Open the Mautic Form you want to configure by going to **Components** > **Forms** and clicking the Form name. + +#. Go to the **Actions** tab inside the Form editor. + +#. Click **Add action**. + +#. Select **Record UTM tags** from the action type dropdown. + +#. Fill in the **Name** field with a label for your own reference, ``Record UTM tags on submit``. The description is optional. + + .. warning:: + + The **Name** and **Description** fields in the action modal confuse almost everyone the first time. They look like configuration, they aren't. The action is entirely automatic once added. there is nothing to configure beyond adding it. + +#. Save the action and then save the Form. + +#. Confirm with the website team that Campaign URLs pointing to Pages with this Form include UTM parameters in the query string, for example: + + .. code-block:: text + + https://yoursite.com/landing-Page?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026 + +#. Test the setup by visiting the Landing Page using a URL with UTM parameters, submitting the Form, then checking the Contact's profile. + +This URL uses ``utm_source=newsletter`` to identify the sending newsletter, ``utm_medium=email`` to identify the delivery Channel, and ``utm_campaign=spring_sale_2026`` to group the submission under the active Campaign. All three values write to the Contact profile once the Form submit, making them available for Segment filters and Campaign conditions. Using real, meaningful values during testing rather than placeholder strings ensures the timeline entry looks exactly as it ins production. + +The choice to use three parameters rather than all five reflects a practical minimum. You can use ``utm_campaign`` as the most important signal for Reporting, while ``utm_source`` and ``utm_medium`` together give you Channel attribution. The optional ``utm_content`` and ``utm_term`` parameters add finer-grained tracking when you need to distinguish between multiple creative variants or paid keyword groups. + +.. note:: + + Forms capture the full Page URL, Page referrer, User agent, and all raw query parameters, not just UTM fields. + +.. tip:: + + If a visitor arrives without UTM parameters in the URL but the Page referrer URL does contain them, they clicked through from a Page that had UTM parameters, falls back to reading those from the Page referrer. Don't rely on this as a primary strategy, but it prevents the data from always being empty in this scenario. + +After saving, the **Record UTM tags** action should appear in the Form's action list. When a Contact submits the Form from a UTM-tagged URL, their profile shows a **UTM tags recorded** timeline entry, separate from the Form submission entry, with the associated Form ID and the captured field values. If UTM fields are empty after a test submission, the URL used during the test didn't contain UTM parameters. that's a website-side issue, not a Mautic configuration issue. + +.. TODO: add screenshot - Contact timeline showing a "UTM tags recorded" entry with populated UTM fields and a FORMID reference + +.. seealso:: + + - :doc:`utm_tags_overview` + - :doc:`utm_tags_landing_pages` + - :doc:`utm_tags_segment_filters` + - :doc:`utm_tags_campaign_conditions` diff --git a/docs/utm_tags/utm_tags_landing_pages.rst b/docs/utm_tags/utm_tags_landing_pages.rst new file mode 100644 index 000000000..632c004e3 --- /dev/null +++ b/docs/utm_tags/utm_tags_landing_pages.rst @@ -0,0 +1,32 @@ +Capturing UTM tags from landing pages +###################################### + +When a known Contact visits a Landing Page, either a Mautic-built Landing Page or an external website with the Mautic tracking script installed, Mautic registers a visit on their profile as behavioral activity. If the URL they landed on contains UTM parameters, Mautic automatically extracts and stores them on the Contact record. This enables segmentation and Reporting based on which Campaigns, Channels, or sources drove that visit. + +There is nothing to configure on the Landing Page or website itself. The UTM parameters must already be present in the URL the Contact clicks, meaning whoever creates the link that brings the Contact there is responsible for including the UTM parameters in it. Mautic reads what's there. + +.. note:: + + There is no action, no field, and no toggle to enable inside the Landing Page itself. If a colleague asks "where do you set up UTM tags on this Landing Page?", the answer is: you set them in the link that brings people there. + +Examples +******** + +The following URLs show how UTM parameters appear on both external websites and Mautic Landing Pages: + +.. code-block:: text + + https://yoursite.com/promo-Page?utm_source=newsletter&utm_medium=Email&utm_campaign=spring_sale_2026 + +.. code-block:: text + + https://your-mautic.com/Page/landing-slug?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale_2026 + +The first URL contains three UTM parameters: ``utm_source`` identifies the traffic origin as a newsletter, ``utm_medium`` identifies the delivery Channel as Email, and ``utm_campaign`` groups the traffic under the ``spring_sale_2026`` Campaign name. The second URL shows the same pattern applied to a Mautic-hosted Landing Page, the slug ``/Page/landing-slug`` is the Mautic Landing Page path, and the query string carries the UTM data. + +Choose parameters to reflect the realistic distribution Channel for each URL. The external website URL uses ``utm_medium=email`` because a newsletter link drove the visit, while the Mautic Landing Page URL uses ``utm_medium=cpc`` because a paid search ad drove it. Using accurate medium values ensures your analytics tool groups traffic into the correct Channels and your Reporting reflects the actual performance of each Channel. + +.. seealso:: + + - :doc:`utm_tags_overview` + - :doc:`utm_tags_forms` diff --git a/docs/utm_tags/utm_tags_overview.rst b/docs/utm_tags/utm_tags_overview.rst new file mode 100644 index 000000000..fff072f01 --- /dev/null +++ b/docs/utm_tags/utm_tags_overview.rst @@ -0,0 +1,162 @@ +.. vale off + +UTM tags overview +################# + +.. vale on + +UTM (Urchin Tracking Module) parameters are short tags appended to URLs that tell analytics tools where a visitor came from, which Campaign, Channel, source, and so on. Mautic has native support for UTM tags across a wide range of its features, but how UTM data flows through the system isn't uniform. Different features capture, generate, store, and use UTM data in different ways, and confusing them leads to gaps in tracking, empty fields, or misplaced expectations. + +Understanding UTM parameters +**************************** + +The five standard UTM parameters are: + +.. list-table:: + :widths: 20, 80 + :header-rows: 1 + + * - Parameter + - Description + * - **utm_source** + - The referring source of the web activity. Indicates the social network, search engine, newsletter name, or any other specific source driving the traffic. Examples: ``facebook``, ``twitter``, ``blog``, ``newsletter`` + * - **utm_medium** + - The Channel or method of delivery. Examples: ``email``, ``cpc``, ``organic_social``, ``organic``, ``social`` + * - **utm_campaign** + - The specific promotion or marketing initiative title that you want to track. Examples: ``summer_sale``, ``free_trial``, ``spring_sale_2026`` + * - **utm_content** + - Optional, used to distinguish between multiple versions of the same message or content variant within a Campaign. Examples: ``welcome_email_1``, ``banner_version_a`` + * - **utm_term** + - Optional, used to track search keywords or content categories. Auto-populated in some contexts. + +You don't need to fill all five parameters. Use one, a few, or all as required for your tracking needs. + +Using UTM tags in Mautic +************************ + +To use UTM tags with Google Analytics where they appear in your Google Analytics Dashboard, you must install your Google Analytics tracking code on the resource you are linking to. This synchronizes with your Google Analytics Dashboard and records the UTM tags. + +If you use a Mautic Landing Page, you must go to Settings > Configuration > Tracking Settings, and add your Google Analytics ID. + +.. image:: ../channels/images/utm_tags/add_google_analytics_id.png + :alt: Screenshot showing the option to add your Google Analytics ID + +If you use a non-Mautic Landing Page, you must manually embed the Google Analytics tracking script on the third-party Page. + +Feature groups +************** + +Inbound capture (recording UTM data) +===================================== + +These features read UTM parameters from URLs and save them to a Contact's record. For this to work, the URL the Contact lands on must already contain UTM parameters, Mautic doesn't add them, it only reads what's there. The link that brings the Contact to that Page is always responsible for carrying the UTM values. + +.. list-table:: + :header-rows: 1 + :widths: 30, 35, 35 + + * - Feature + - How it triggers + - Notes + * - **Form action "Record UTM tags"** + - Visitor submits a Mautic Form that has this action configured. Reads UTM parameters from the query string of the Page the Form is on, with Page referrer as fallback. + - See :doc:`utm_tags_forms` + * - **Tracking script / pixel on external site** + - The tracking script fires on an external Page. The browser call carries the full Page URL, if it contains UTM parameters, they're captured. + - See :doc:`utm_tags_landing_pages` + * - **Mautic Landing Page visit** + - Someone visits a Page built inside Mautic (``/Page/slug``). UTM parameters are read from the URL query string. + - See :doc:`utm_tags_landing_pages` + * - **Asset download** + - On direct Asset download via a UTM-tagged URL, stores UTM parameters on the download record only, not on the Contact profile. UTM data isn't captured when the download trigger by a Form action. + - See :doc:`utm_tags_asset_downloads` + +Outbound tagging (appending UTM to links) +========================================== + +These features take UTM values you configure inside Mautic and automatically stamp them onto every tracked link in the content when it's delivered or rendered. There is nothing to add to the links themselves, you fill in the UTM fields on the content object and handles the appending. + +.. list-table:: + :header-rows: 1 + :widths: 25, 30, 45 + + * - Feature + - Where UTM configure + - How it triggers + * - **Email** + - UTM fields on the Email record + - When an Email send or previewed. Every tracked link in the Email body gets the configured UTM parameters appended. + * - **Dynamic Web Content** + - UTM fields on the Dynamic Web Content (DWC) block + - When a Dynamic Web Content (DWC) block render for a visitor (either via Campaign or slot-based). Tracked links in the block content have UTM parameters appended at render time. + * - **Push notifications** + - UTM fields on the notification + - When a web/mobile push notification send. Tracked URLs inside the notification payload have UTM parameters appended before delivery. + * - **Focus Items** + - UTM fields on the Focus Item configuration + - When a Focus Item displays on a webpage. Tracked links inside the Focus Item content have UTM parameters appended when rendered. + +Using UTM data for targeting +============================= + +Once UTM data has capture on Contact profiles, it may use to control who include in a Segment or how a Contact route through a Campaign. + +.. list-table:: + :header-rows: 1 + :widths: 25, 35, 40 + + * - Feature + - What it does + - How it triggers + * - **Segment filters** + - Includes or excludes Contacts from a Segment based on UTM values ever recorded on them. + - When a Segment is evaluated. All five UTM fields (``utm_source``, ``utm_medium``, ``utm_campaign``, ``utm_content``, ``utm_term``) are available as filter conditions. + * - **Campaign conditions** + - Branches Campaign flow based on UTM field values on the Contact. + - When a Campaign evaluates a "Contact field value" condition node that references a UTM field. + +Displaying UTM data +==================== + +Captured UTM data surfaces in several places for visibility and Reporting. + +.. list-table:: + :header-rows: 1 + :widths: 25, 75 + + * - Feature + - What it does + * - **Contact timeline** + - Each time UTM tags are saved to a Contact, a timeline entry appears. The icon changes based on ``utm_medium`` (Email, social, ad, Cost Per Click (CPC), etc.). The label uses ``utm_campaign`` if available. + * - **Reports** + - A dedicated Report source joins the UTM tags table with Contacts, letting you build Reports filtered or grouped by any UTM field. + * - **Asset Reports** + - Asset download Reports expose all five UTM fields. + +REST API +========= + +Two REST endPoints manage UTM data directly on Contacts: + +- ``POST /contacts/{id}/utm/add``, accepts the full UTM payload (all five tags plus ``url``, ``referrer``, ``User_agent``, etc.) +- ``POST /contacts/{id}/utm/{utmid}/remove``, removes existing UTM tags from a Contact record + +How to understand each group +***************************** + +The most common source of confusion with Mautic's UTM system is treating all features as equivalent. They aren't: + +- **Inbound capture** depends entirely on UTM parameters being in the URL. Mautic reads, it doesn't write. +- **Outbound tagging** is the reverse, writes UTM parameters onto links, based on what you configured on the content object. +- **Targeting** only works with data that was already captured inbound. You can't Segment or branch on UTM data that was never recorded on the Contact. +- **Asset download UTM data** lives in a separate table and doesn't feed into Contact profiles, Segment filters, or Campaign conditions. + +.. seealso:: + + - :doc:`utm_tags_landing_pages` + - :doc:`utm_tags_asset_downloads` + - :doc:`utm_tags_forms` + - :doc:`utm_tags_emails` + - :doc:`utm_tags_dynamic_web_content` + - :doc:`utm_tags_campaign_conditions` + - :doc:`utm_tags_segment_filters` diff --git a/docs/utm_tags/utm_tags_segment_filters.rst b/docs/utm_tags/utm_tags_segment_filters.rst new file mode 100644 index 000000000..7f1439727 --- /dev/null +++ b/docs/utm_tags/utm_tags_segment_filters.rst @@ -0,0 +1,50 @@ +.. vale off + +UTM tags as Segment filters +############################ + +.. vale on + +Segments can include or exclude Contacts based on UTM values recorded on their profile. All five standard UTM fields are available as filter conditions: ``utm_source``, ``utm_medium``, ``utm_campaign``, ``utm_content``, and ``utm_term``. This lets you build Segments like "all Contacts who came from the spring sale Email Campaign" or "all Contacts whose source was Google," and use those Segments for targeted sends, Reporting, or Campaign entry Points. + +The UTM data queried here comes from the **Record UTM Tags** Form action and from Landing Page visits and tracked website pages where UTM parameters exist in the URL. UTM data from Asset downloads stores separately and isn't available in Segment filters. To follow the steps below, Contacts must have UTM data on their profile and you need permission to create or edit Segments in Mautic. + +Create segment filters +********************** + +#. Go to **Segments** and open an existing Segment or create a new one. + +#. Go to the **Filters** tab. + +#. Click **Add filter** and search for the UTM field you want to filter on. All five are available under their corresponding labels: + + - ``utm_source`` + - ``utm_medium`` + - ``utm_campaign`` + - ``utm_content`` + - ``utm_term`` + +#. Select the operator and enter the value to match, ``newsletter``, ``email``, or ``spring_sale_2026``. + +#. Save the Segment. + +The preceding example applies the operator and value ``newsletter`` to ``utm_source``, which selects all Contacts who recorded ``newsletter`` as their source at any point in their history. You could equally filter on ``utm_medium = email`` to target all Email-acquired Contacts, or combine both filters with and logic to narrow the audience to Contacts acquired specifically via the newsletter Channel using Email delivery. + +Combine filters this way to reflect how UTM parameters work together. Filtering on a single field, ``utm_campaign`` alone, for instance, can include Contacts from multiple Channels. Adding a second filter on ``utm_medium`` narrows the Segment to Contacts from a specific Channel within that Campaign, which is often the more actionable audience for a targeted send. + +.. note:: + + Segment UTM filters match against values **ever recorded** on the Contact, not just the most recent visit. If a Contact has tag with multiple Campaigns over time, they may match a filter for an older Campaign even if their latest activity was from a different one. + +.. tip:: + + Combining UTM filters with other Segment conditions, for example, "came from Campaign X and submitted Form Y," is a powerful way to build high-intent audiences. UTM filters alone tell you the source. Pairing them with behavioral filters tells you the source and what the Contact did. + +After the Segment updates, it should show Contacts whose recorded UTM values match your filter conditions, with Contacts that have no UTM data or non-matching values correctly excluded. + +.. seealso:: + + - :doc:`utm_tags_overview` + - :doc:`utm_tags_forms` + - :doc:`utm_tags_campaign_conditions` + - :doc:`/segments/manage_segments`