> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkutm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UTM rules

> Workspace-wide validation and standardization that runs on every link save.

<Tip>
  Setting up UTM Rules for the first time? Start with the [UTM naming convention](/playbooks/utm-naming-convention) playbook to define your approved source, medium, and campaign values before configuring the rules engine.
</Tip>

UTM Rules is a set of rules that runs whenever a link is created or updated. One rule set per workspace. It applies in this order:

1. **Force lowercase** (default ON) - `Summer_Sale` → `summer_sale`
2. **Space replacement** (default `_`) - `summer sale` → `summer_sale`
3. **Max length** (default 100) - reject values longer than this
4. **Prohibited values** - fail if value contains any banned term
5. **Allowed characters** - fail if value contains characters outside the selected set (lowercase, numbers, dots, hyphens)

## When to use it

* Marketing team of more than one person - drift is guaranteed without rules.
* Anyone publishing UTMs to a shared analytics tool (GA, Mixpanel) where casing/typos create duplicate rows.
* Agencies enforcing client-specific naming conventions.

## How to configure

<Steps>
  <Step title="Open the rules page">
    Sidebar → **UTM Rules**.
  </Step>

  <Step title="Set the basics">
    <Frame>
      <img src="https://mintcdn.com/utm-e577acb5/_OFWyAVC_YtnhKc0/images/utmrulesspacecharacter.png?fit=max&auto=format&n=_OFWyAVC_YtnhKc0&q=85&s=baf920b2fe342b58529edf79bdd4decd" alt="Space Character dropdown - Underscore selected, with Hyphen, Plus, URL Encoded, and Remove spaces options each showing a live preview" width="1920" height="991" data-path="images/utmrulesspacecharacter.png" />
    </Frame>
  </Step>

  <Step title="Set the basics">
    <Frame>
      <img src="https://mintcdn.com/utm-e577acb5/_OFWyAVC_YtnhKc0/images/utmrulesspacecharacter.png?fit=max&auto=format&n=_OFWyAVC_YtnhKc0&q=85&s=baf920b2fe342b58529edf79bdd4decd" alt="Space Character dropdown - Underscore selected, with Hyphen, Plus, URL Encoded, and Remove spaces options each showing a live preview" width="1920" height="991" data-path="images/utmrulesspacecharacter.png" />
    </Frame>
  </Step>

  <Step title="Save and test">
    Try creating a link with bad values. Validation errors appear inline on the failing fields.
  </Step>
</Steps>

<Frame>
  <img src="https://mintcdn.com/utm-e577acb5/nHQFp_ZWa_EOApO0/images/utmrules.png?fit=max&auto=format&n=nHQFp_ZWa_EOApO0&q=85&s=4d65058ae674b389573c108cd1ce87a1" alt="UTM Rules page - Space Character, Force Lowercase toggle, Max Length, Allowed Characters checkboxes (lowercase, numbers, dots, hyphens), and Prohibited Values settings" width="1919" height="956" data-path="images/utmrules.png" />
</Frame>

## Real-world example

<Tabs>
  <Tab title="Force consistency">
    ```text theme={null}
    forceLowercase: true
    spaceCharacter: "_"
    allowedCharactersRegex: "^[a-z0-9_-]+$"
    prohibitedValues: ["test", "draft", "tbd"]
    ```

    No more `Summer Sale!` slipping into prod.
  </Tab>

  <Tab title="Require campaign">
    ```text theme={null}
    Required field rule:
    {
      validationType: "not_empty",
      requiredParameters: ["campaign"],
      description: "Campaign name is required"
    }
    ```

    Every link must have `utm_campaign`.
  </Tab>

  <Tab title="Allow only known sources">
    ```text theme={null}
    Required field rule:
    {
      validationType: "allowed_values",
      requiredParameters: ["source"],
      allowedValues: ["google", "facebook", "linkedin", "newsletter"]
    }
    ```

    Anything outside the list fails.
  </Tab>

  <Tab title="Auto-fill medium">
    ```text theme={null}
    Conditional logic rule:
    if ifField=source, condition=equals, ifValue=google
    then set thenSet=medium, toValue=cpc
    ```

    Anyone picking `source=google` gets `medium=cpc` automatically.
  </Tab>
</Tabs>

**Force consistency across the whole team:**

* **Force lowercase**: on
* **Space character**: hyphen
* **Allowed characters**: select lowercase, numbers, dots, hyphens
* **Blocked values**: test, draft, tbd

No more `Summer Sale!` slipping into prod.

## Edge cases

<Note>
  **Rules cleaning vs validation.** Steps 1-2 (lowercase, space replacement) **transform** values silently. Steps 3-5 (length, prohibited, allowed characters) **reject** the save with errors.
</Note>

<Note>
  **Default rules ship per workspace.** Every new workspace starts with force lowercase on, underscore for spaces, and a 100-character max length automatically. They CAN be turned off using the toggle given in the UTM rules panel but it is ON by default.
</Note>