diff --git a/.github/styles/config/vocabularies/Mautic/accept.txt b/.github/styles/config/vocabularies/Mautic/accept.txt index cf9327886..1e0779d1a 100644 --- a/.github/styles/config/vocabularies/Mautic/accept.txt +++ b/.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 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/images/utm_tags/utm_tags_recorded_timeline.png b/docs/channels/images/utm_tags/utm_tags_recorded_timeline.png new file mode 100644 index 000000000..b2797c5cd Binary files /dev/null and b/docs/channels/images/utm_tags/utm_tags_recorded_timeline.png differ diff --git a/docs/channels/utm_tags.rst b/docs/channels/utm_tags.rst deleted file mode 100644 index d95c056dd..000000000 --- a/docs/channels/utm_tags.rst +++ /dev/null @@ -1,92 +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_ga_code.png - :width: 400 - :alt: Screenshot showing the option to add Google Analytics code - -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..004e07442 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 tracked links in Dynamic Web Content. See :doc:`/utm_tags/utm_tags_overview` for more information. .. vale off diff --git a/docs/index.rst b/docs/index.rst index 42b0094f9..b54838fc9 100644 --- a/docs/index.rst +++ b/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 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..da88b6a5e --- /dev/null +++ b/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` 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..dc99d822e --- /dev/null +++ b/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` 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..6d29996aa --- /dev/null +++ b/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` diff --git a/docs/utm_tags/utm_tags_emails.rst b/docs/utm_tags/utm_tags_emails.rst new file mode 100644 index 000000000..5b29301fa --- /dev/null +++ b/docs/utm_tags/utm_tags_emails.rst @@ -0,0 +1,59 @@ +.. vale off + +UTM tags in Email +################# + +.. vale on + +Mautic automatically appends your UTM parameters to every trackable link inside the Email body when you send or preview the Email. This means a clean link like ``https://example.com/promo`` in your Email becomes ``https://example.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 name** 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. + +.. vale off + +Configure Email UTM tags +************************ + +.. vale on + +#. Open the Email to start editing: + + #. Go to **Channels** > **Emails**. + #. Click the name of the Email 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 Email body content. + +#. Fill in the UTM fields you want to apply to links in the Email: + + * **Campaign source**: where the Email originates, for example, ``newsletter`` or ``mautic`` + * **Campaign medium**: the Channel type, for example, ``email`` + * **Campaign name**: the Campaign name, for example, ``spring_sale_2026`` + * **Campaign content**: optional field for distinguishing between multiple Emails in the same Campaign, for example, ``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://example.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 Landing Page. After a real send, traffic appears as a distinct source or medium combination in your analytics platform. + +.. 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..3bd4d24fa --- /dev/null +++ b/docs/utm_tags/utm_tags_forms.rst @@ -0,0 +1,67 @@ +.. 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 Landing Page URL and store them on their profile. A built-in Mautic Form action called **Record UTM Tags** handles this, 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 Landing Page where the Form lives. + +That means the website is responsible for including UTM parameters in the Landing Page URL. The Form action 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 Landing Page where the site sends UTM-tagged traffic. + +.. vale off + +Add UTM recording +***************** + +.. vale on + +#. Open the Form to start editing: + + #. Go to **Components** > **Forms**. + #. Click the name of the Form you want to modify. + #. Click **Edit**. + +#. Go to the **Actions** tab inside the Form editor. + +#. Open the **Add a new submit action** dropdown menu and select **Record UTM Tags**. + +#. Fill in the **Name** field with a label for your reference, for example, ``Record UTM Tags on submit``. The description is optional. + + .. attention:: + + The **Name** and **Description** fields in the action dialog represent organizational labels, **not** configuration settings. The action operates automatically once added, and requires no further parameter configuration. + +#. Save the action and save the Form. + +#. Confirm with the website team that Campaign URLs pointing to Landing Pages with this Form include UTM parameters in the query string, for example: + + .. code-block:: text + + https://example.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, and checking the Contact 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. Mautic writes all three values to the Contact profile once the Contact submits the Form, 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 does in 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 Landing Page URL, Landing Page referrer, the browser's ``User-Agent`` string, and all raw query parameters, not just UTM fields. + +.. tip:: + + If a visitor arrives without UTM parameters in the URL but the Landing Page referrer URL contains them, meaning they clicked through from a Landing Page that had UTM parameters, Mautic falls back to reading parameters from the Landing Page referrer. Don't rely on this as a primary strategy, but it prevents UTM fields from remaining empty in this scenario. + +After saving, the **Record UTM Tags** action appears in the Form's action list. When a Contact submits the Form from a UTM-tagged URL, their profile displays a **UTM tags recorded** timeline entry, separate from the Form submission entry, displaying the associated Form ID and captured field values. If UTM fields remain empty after a test submission, the URL used during testing didn't contain UTM parameters. This indicates a website-side link configuration issue rather than a Mautic configuration issue. + +.. image:: ../channels/images/utm_tags/utm_tags_recorded_timeline.png + :alt: Contact activity timeline showing a 'UTM tags recorded' entry with populated UTM fields and a Form ID 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..69b366f9c --- /dev/null +++ b/docs/utm_tags/utm_tags_landing_pages.rst @@ -0,0 +1,42 @@ +.. vale off + +Capturing UTM tags from Landing Pages +##################################### + +.. vale on + +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:: + + 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. + +Examples +******** + +The following URLs show how UTM parameters appear on both external websites and Mautic Landing Pages: + +.. code-block:: text + + https://example.com/promo-page?utm_source=newsletter&utm_medium=email&utm_campaign=spring_sale_2026 + +.. code-block:: text + + https://your-mautic.com/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 source as a newsletter +* ``utm_medium``: identifies the delivery Channel as Email +* ``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: ``landing-slug`` is the Mautic Landing Page alias, and the query string carries the same 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..80ec0e2df --- /dev/null +++ b/docs/utm_tags/utm_tags_overview.rst @@ -0,0 +1,166 @@ +UTM tags overview +################# + +.. vale off + +UTM tags - Urchin Tracking Module - are short tags added to URLs that tell analytics tools where traffic comes from, including the specific Campaign, Channel, or source. Mautic supports UTM tags across many features, though each feature handles UTM data differently. Features capture, generate, store, and use UTM data in distinct ways. Confusing how these features handle the data causes gaps in tracking, empty fields, or incorrect expectations. + +.. vale on + +Understanding UTM parameters +**************************** + +The five standard UTM parameters are: + +.. vale off + +.. 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 to track. Examples: ``summer_sale``, ``free_trial``, ``spring_sale_2026`` + * - **utm_content** + - **Optional**. Use this 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**. Use this to track search keywords or content categories. Auto-populated in some contexts. + +.. vale on + +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, go to **Settings** > **Configuration** > **Tracking Settings**, and add your **Google Analytics ID**. + +.. image:: ../channels/images/utm_tags/add_ga_code.png + :alt: Google Analytics ID field in Mautic's Tracking Settings + +If you use a non-Mautic Landing Page, you must manually embed the Google Analytics tracking script on the third-party Landing 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 Landing Page is always responsible for carrying the UTM values. + +.. list-table:: + :header-rows: 1 + :widths: 30, 35, 35 + + * - Feature + - How it triggers + - Notes + * - **Record UTM Tags** Form action + - Visitor submits a Mautic Form that has this action configured. It reads UTM parameters from the query string of the Landing Page the Form is on, with Landing Page referrer as fallback. + - See :doc:`utm_tags_forms` + * - **Tracking script / pixel on external site** + - The tracking script fires on an external Landing Page. The browser call carries the full Landing Page URL. If it contains UTM parameters, Mautic captures them. + - See :doc:`utm_tags_landing_pages` + * - **Mautic Landing Page visit** + - Someone visits a Landing Page built inside Mautic, for example ``https://your-mautic.com/{alias}``. Mautic reads UTM parameters from the URL query string. + - See :doc:`utm_tags_landing_pages` + * - **Asset download** + - On direct Asset download via a UTM-tagged URL, Mautic stores UTM parameters on the download record only, not on the Contact profile. Mautic doesn't capture UTM data when a Form action triggers the download. + - 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 Mautic handles the appending. + +.. list-table:: + :header-rows: 1 + :widths: 25, 30, 45 + + * - Feature + - Where you configure UTM + - How it triggers + * - **Email** + - UTM fields on the Email record + - When you send or preview an Email. Mautic appends the configured UTM parameters to every tracked link in the Email body. + * - **Dynamic Web Content** + - UTM fields on the Dynamic Web Content - DWC - block + - When a DWC block renders for a visitor, either via Campaign or slot-based. Mautic appends UTM parameters to tracked links in the block content at render time. + * - **Push notifications** + - UTM fields on the notification + - When Mautic sends a web or mobile push notification. Mautic appends UTM parameters to tracked URLs inside the notification payload before delivery. + * - **Focus Items** + - UTM fields on the Focus Item configuration + - When a Focus Item displays on a webpage. Mautic appends UTM parameters to tracked links inside the Focus Item content when it renders. + +Using UTM data for targeting +============================ + +Once Mautic captures UTM data on Contact profiles, you can use it to control who Mautic includes in a Segment or how a Contact routes 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 Mautic evaluates a Segment. All five UTM Contact 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 that references a UTM field. + +Displaying UTM data +=================== + +Captured UTM data surfaces in several places for visibility and Reports. + +.. list-table:: + :header-rows: 1 + :widths: 25, 75 + + * - Feature + - What it does + * - **Contact timeline** + - Each time Mautic saves UTM tags to a Contact, a timeline entry appears. The icon changes based on ``utm_medium`` - Email, social, ad, Cost Per Click - CPC, and so on. 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 include data for all five UTM parameters - ``utm_source``, ``utm_medium``, ``utm_campaign``, ``utm_content``, and ``utm_term``. + +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``, ``referer``, and ``user_agent`` +* ``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. Mautic writes UTM parameters onto links, based on what you configured on the content object. +* **Targeting** only works with data that inbound capture already recorded. You can't Segment or branch on UTM data that inbound capture 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..db3b8903f --- /dev/null +++ b/docs/utm_tags/utm_tags_segment_filters.rst @@ -0,0 +1,64 @@ +.. 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`` +* ``utm_term`` + +These UTM fields let you build Segments - for example, 'all Contacts who came from the spring sale Email Campaign' or 'all Contacts whose source was Google' - and use those Segments for targeted sends, Reports, or as a Campaign's Contact source. + +.. vale off + +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. Mautic stores UTM data from Asset downloads separately, and it 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. + +.. vale on + +.. vale off + +Create Segment filters +********************** + +.. vale on + +.. vale off + +#. Go to **Segments** and open an existing Segment or create a new one. + +#. Go to the **Filters** tab. + +#. Click the **Choose one...** menu and search for ``utm``. The **Contact** group lists the five UTM filters: **UTM Campaign**, **UTM Content**, **UTM Medium**, **UTM Source**, and **UTM Term**. Select the filter you want to use. + +#. Select the operator and enter the value to match, for example, ``newsletter``, ``email``, or ``spring_sale_2026``. + +#. Save the Segment. + +.. vale on + +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 UTM tags from 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`