Skip to content
Documentation

How-To: Mautic - UTM tags

UTM 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 is not 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.

Related links:

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 does not add them, it only reads what is there. The link that brings the contact to that page is always responsible for carrying the UTM values.

Feature How it triggers
Form action "Record UTM tags" Visitor submits a Mautic form that has this action configured. Reads UTM params from the query string of the page the form is on + HTTP referer as fallback.
Tracking script / pixel on external site The tracking script fires on an external page (your website). The browser call carries the full page URL — if it contains UTM params, they are captured.
Mautic landing page visit Someone visits a page built inside Mautic (/page/slug). UTM params are read from the URL query string.
Asset download On direct asset download via a UTM-tagged URL — stores UTM params on the download record only, not on the contact profile. Not captured when the download is triggered by a form action.

These features take UTM values you configure inside Mautic and automatically stamp them onto every tracked link in the content when it is 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.

Feature Where UTM is configured How it triggers
Email UTM fields editing the email When an email is sent or previewed. Every tracked link in the email body gets the configured UTM params appended.
Dynamic Web Content UTM fields editing DWC When a DWC block is rendered for a visitor (either via campaign or slot-based). Tracked links in the block content have UTM params appended at render time.
Push notifications UTM fields editing the notification When a web/mobile push notification is sent. Tracked URLs inside the notification payload have UTM params appended before delivery.

Using UTM data for targeting

Once UTM data has been captured on contact profiles, it can be used to control who is included in a segment or how a contact is routed through a campaign.

Feature What it does How it triggers
Segment filters Includes/excludes contacts from a segment based on UTM values ever recorded on them When a segment is evaluated. All 5 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" decision node that references a UTM field.

Displaying UTM data

Captured UTM data surfaces in several places for visibility and reporting.

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, cpc, etc.). The label uses utm_campaign if available.
Reports A dedicated report source joins the UTM tags table with contacts', lets you build reports filtered/grouped by any UTM field
Asset reports Asset download reports expose all 5 UTM fields

API

Two REST endpoints manage UTM data directly on contacts:

  • POST /contacts/{id}/utm/add → accepts the full UTM payload (all 5 tags + url, referer, user_agent, etc.)
  • POST /contacts/{id}/utm/{utmid}/remove → removes existing UTM tags

How to understand each group

The most common source of confusion with Mautic's UTM system is treating all features as equivalent. They are not:

  • Inbound capture depends entirely on UTM params being in the URL -> Mautic reads, it does not write.
  • Outbound tagging is the reverse -> Mautic writes UTM params onto links, based on what you configured on the content object.
  • Targeting only works with data that was already captured inbound -> you cannot segment or branch on UTM data that was never recorded on the contact.
  • Asset download UTM data lives in a separate table and does not feed into contact profiles, segment filters, or campaign conditions.
← Previous How-To - Mautic - Tokens Next → Overview