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

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. Otherwise, create a disabled automation with a send-email block to work with.

See endpoint: Create automation

curl -X POST 'https://api.omnisend.com/api/automations' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-preview' \
  -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

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-preview'

The response shows the synthesized defaults:

{
  "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

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-preview' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "source": "omnisend",
      "medium": "email",
      "campaign": "welcome-series-2026"
    }
  }'

The response confirms the stored values:

{
  "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

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-preview' \
  -H 'Content-Type: application/json' \
  -d '{
    "tags": {
      "source": "",
      "medium": "",
      "campaign": ""
    }
  }'

The response shows the defaults restored:

{
  "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

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

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

{
  "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.