HomeGuidesAPI Reference
Need Help?
Guides
Need Help?

How to configure UTM tags for campaigns

Intro

Customize the UTM parameters appended to links in your campaign emails so clicks are attributed correctly in Google Analytics and other analytics tools. Each campaign gets three tags — source, medium, and campaign — with sensible defaults that you can override before sending. A/B test campaigns support per-variant UTM tags, so each variant can be tracked independently.

See API reference: Campaigns

Prerequisites

  • An API key with campaigns.read and campaigns.write scopes, or an OAuth token with the same scopes
  • A draft email campaign (regular or A/B test) — UTM tags can only be updated while the campaign is in draft status

Step 1: Create a draft campaign

Create a regular email campaign that you will configure UTM tags for. If you already have a draft campaign, skip to Step 2.

See endpoint: Create campaign

curl -X POST 'https://api.omnisend.com/api/campaigns' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-preview' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Summer Sale Announcement",
    "type": "regular",
    "channel": "email",
    "language": "en_US",
    "content": {
      "email": {
        "subject": "Summer Sale — Up to 50% Off!",
        "senderName": "My Store",
        "templateID": "000000000000000000000001"
      }
    }
  }'

Save the id from the response — you will use it in the next steps.

Step 2: Read the default UTM tags

Every campaign has UTM tags, even if you never set them. The GET endpoint returns either stored values or synthesized defaults.

See endpoint: Get campaign UTM settings

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

For a regular campaign the response contains a tags object:

{
  "tags": {
    "source": "omnisend",
    "medium": "email",
    "campaign": "campaign: Summer Sale Announcement (68beca12d2e99b0c8d19fd5e)"
  }
}

The defaults are:

FieldDefault value
sourceomnisend
mediumThe campaign channel — email, sms, or push
campaigncampaign: <campaign name> (<campaign id>)

Step 3: Update UTM tags

Replace the UTM tags with your own values. The PUT endpoint uses full replacement — provide all three fields. Send an empty string for any field you want to reset to its default.

See endpoint: Update campaign UTM settings

curl -X PUT 'https://api.omnisend.com/api/campaigns/CAMPAIGN_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": "summer-sale-2026"
    }
  }'

The response returns the updated tags:

{
  "tags": {
    "source": "omnisend",
    "medium": "email",
    "campaign": "summer-sale-2026"
  }
}

Note: UTM tags can only be updated while the campaign is in draft status. Attempting to update a sent or scheduled campaign returns 409 Conflict.

Step 4: Configure per-variant UTM tags for A/B test campaigns

A/B test campaigns have separate UTM tags for each variant, so you can distinguish variant performance in your analytics. Instead of tags, the request and response use a variants object with keys a and b.

Create an A/B test campaign first (see How to send an A/B test campaign), then read its UTM defaults:

See endpoint: Get campaign UTM settings

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

The response includes per-variant tags, each with the variant's id:

{
  "variants": {
    "a": {
      "id": "000000000000000000000010",
      "tags": {
        "source": "omnisend",
        "medium": "email",
        "campaign": "campaign: Subject Line Test (68beca12d2e99b0c8d19fd5e)"
      }
    },
    "b": {
      "id": "000000000000000000000011",
      "tags": {
        "source": "omnisend",
        "medium": "email",
        "campaign": "campaign: Subject Line Test (68beca12d2e99b0c8d19fd5e)"
      }
    }
  }
}

Update both variants' UTM tags in a single request:

See endpoint: Update campaign UTM settings

curl -X PUT 'https://api.omnisend.com/api/campaigns/AB_CAMPAIGN_ID/utm' \
  -H 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  -H 'Omnisend-Version: 2026-preview' \
  -H 'Content-Type: application/json' \
  -d '{
    "variants": {
      "a": {
        "source": "omnisend",
        "medium": "email",
        "campaign": "subject-test-variant-a"
      },
      "b": {
        "source": "omnisend",
        "medium": "email",
        "campaign": "subject-test-variant-b"
      }
    }
  }'

Note: The request body must match the campaign type — use tags for regular campaigns and variants for A/B test campaigns. Providing the wrong shape returns a validation error. Providing both tags and variants in one request is also rejected.

Verify results

Read the UTM tags back to confirm your changes were applied.

See endpoint: Get campaign UTM settings

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

The response should reflect the values you set. Any field you sent as an empty string will show its synthesized default.

Troubleshooting

  • 409 Conflict on PUT: The campaign is not in draft status. UTM tags can only be updated before the campaign is sent. If the campaign has already been sent or scheduled, copy it to create a new draft.
  • Validation error — wrong body shape: You sent tags to an A/B campaign or variants to a regular campaign. Check the campaign type and use the matching body shape.
  • Validation error — both tags and variants: The request body must contain exactly one of tags or variants, not both.
  • Tag value exceeds 250 characters: Each UTM field (source, medium, campaign) accepts a maximum of 250 characters.

Related resources