---
updatedAt: 2026-06-12T07:54:14.000Z
agentTools:
  projectIndex: https://api-docs.omnisend.com/llms.txt
---

# How to configure UTM tags for automations

## Intro

Customize UTM tracking parameters on automation send blocks so you can attribute traffic from automated emails, SMS, and push notifications in your analytics tool. Each send-action block gets default UTM values automatically — override them per-block when you need finer campaign attribution.

See API reference: [Automations](https://api-docs.omnisend.com/v2026-03-15/reference/automations)

## Prerequisites

* An API key with `automations.read` and `automations.write` scopes (or an OAuth token with the same scopes)
* An existing automation with at least one send-action block (`sendEmail`, `sendSms`, or `sendPush`)

## Step 1: Create a test automation with an email block

If you already have an automation, skip to [Step 2](#step-2-read-the-default-utm-tags). Otherwise, create a disabled automation with a send-email block to work with.

See endpoint: [Create automation](https://api-docs.omnisend.com/v2026-03-15/reference/post_automations)

```sh
curl -X POST 'https://api.omnisend.com/api/automations' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-03-15' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "UTM Test Automation",
    "trigger": {
      "condition": {
        "event": "subscribed to marketing"
      }
    },
    "blocks": [
      {
        "temporaryID": "wait-1h",
        "type": "delay",
        "delay": {
          "mode": "duration",
          "duration": {
            "amount": 1,
            "units": "h"
          }
        }
      },
      {
        "temporaryID": "welcome-email",
        "type": "action",
        "action": {
          "type": "sendEmail",
          "sendEmail": {
            "subject": "Welcome!",
            "senderName": "My Store",
            "preheader": "Thanks for subscribing",
            "language": "en_US",
            "templateID": "000000000000000000000001"
          }
        }
      }
    ]
  }'
```

The response returns the automation in disabled state. Note the automation `id` and the email block's `id` from the `blocks` array — you need both for the UTM endpoints.

> **Note**: Automations are always created disabled. Do not enable the automation while testing UTM configuration.

## Step 2: Read the default UTM tags

Every send-action block has default UTM values even before you configure anything. Retrieve them to see what gets appended to links automatically.

See endpoint: [Get UTM tags for an automation block](https://api-docs.omnisend.com/v2026-03-15/reference/get_automations-id-blocks-blockid-utm)

```sh
curl -X GET 'https://api.omnisend.com/api/automations/AUTOMATION_ID/blocks/BLOCK_ID/utm' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-03-15'
```

The response shows the synthesized defaults:

```json
{
  "tags": {
    "source": "omnisend",
    "medium": "email",
    "campaign": "automation: UTM Test Automation (AUTOMATION_ID)"
  }
}
```

Default values by field:

| Field      | Default value                                     |
| ---------- | ------------------------------------------------- |
| `source`   | `omnisend`                                        |
| `medium`   | Channel name — `email`, `sms`, or `push`          |
| `campaign` | `automation: {automation name} ({automation id})` |

## Step 3: Override UTM tags for a block

Set custom UTM values to match your analytics naming conventions. All three fields must be provided — the update is atomic.

See endpoint: [Update UTM tags for an automation block](https://api-docs.omnisend.com/v2026-03-15/reference/put_automations-id-blocks-blockid-utm)

```sh
curl -X PUT 'https://api.omnisend.com/api/automations/AUTOMATION_ID/blocks/BLOCK_ID/utm' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-03-15' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "source": "omnisend",
      "medium": "email",
      "campaign": "welcome-series-2026"
    }
  }'
```

The response confirms the stored values:

```json
{
  "tags": {
    "source": "omnisend",
    "medium": "email",
    "campaign": "welcome-series-2026"
  }
}
```

> **Note**: Each field has a 250-character maximum. All three fields (`source`, `medium`, `campaign`) are required in every request — you cannot update a single field in isolation.

## Step 4: Reset a field to its default

Send an empty string for any field to clear it. The next read returns the default value for that field.

See endpoint: [Update UTM tags for an automation block](https://api-docs.omnisend.com/v2026-03-15/reference/put_automations-id-blocks-blockid-utm)

```sh
curl -X PUT 'https://api.omnisend.com/api/automations/AUTOMATION_ID/blocks/BLOCK_ID/utm' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-03-15' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "source": "",
      "medium": "",
      "campaign": ""
    }
  }'
```

The response shows the defaults restored:

```json
{
  "tags": {
    "source": "omnisend",
    "medium": "email",
    "campaign": "automation: UTM Test Automation (AUTOMATION_ID)"
  }
}
```

## Verify results

Use the aggregated endpoint to view UTM tags across all send-action blocks in one request.

See endpoint: [Get aggregated UTM tags for all blocks](https://api-docs.omnisend.com/v2026-03-15/reference/get_automations-id-utm)

```sh
curl -X GET 'https://api.omnisend.com/api/automations/AUTOMATION_ID/utm' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-03-15'
```

The response lists each send-action block with its current tags (custom or default):

```json
{
  "blocks": [
    {
      "blockID": "BLOCK_ID",
      "tags": {
        "source": "omnisend",
        "medium": "email",
        "campaign": "welcome-series-2026"
      }
    }
  ]
}
```

Only `sendEmail`, `sendSms`, and `sendPush` blocks appear in this list — delay, split, tag, and webhook blocks do not support UTM tracking.

## Troubleshooting

* **404 on the UTM endpoint**: The block ID does not refer to a send-action block (`sendEmail`, `sendSms`, or `sendPush`). Webhook, tag, delay, and split blocks do not support UTM. Verify the block type in the automation's `blocks` array.
* **400 validation error**: All three fields (`source`, `medium`, `campaign`) are required. You cannot omit a field — send an empty string to reset it instead.
* **404 on automation**: The automation may have been deleted or is in a report-only state. Only active (disabled or enabled) automations support UTM operations.

## Related resources

* [Automations API reference](https://api-docs.omnisend.com/v2026-03-15/reference/automations)
* [Automations overview](https://api-docs.omnisend.com/v2026-03-15/docs/automations)
* [How to configure UTM tags for campaigns](https://api-docs.omnisend.com/v2026-03-15/docs/how-to-configure-utm-tags-for-campaigns)
* [UTM parameters (Help Center)](https://support.omnisend.com/en/articles/1061818-utm-parameters)