Campaign URL Builder

Overview

You send a link and the campaign parameters you want on it, and we hand back the tagged URL. Only the nine campaign parameter names analytics products read are accepted, so a mistyped name comes back as an error instead of disappearing into your warehouse as a missing channel. Nothing is invented: every parameter emitted is one you sent. If the link already carries one of them you decide what happens — refuse, replace, keep what is there, or add a second occurrence beside it. Path, existing query and fragment are copied character for character, so a link that is already encoded cannot come back double-encoded, and we never fetch, resolve or canonicalise anything.

Campaign links are assembled by hand, in spreadsheets and in templates, and every one of those quietly accepts a mistyped parameter name or an encoder that writes a plus sign where a percent escape belongs. You get one encoding, one order, one closed name list, and an error when something does not fit.

When to use it

Scope

Non-goals

• Invents no parameter value — no default source, medium or campaign id
• Does not sort the query; signing wants sorted keys and that belongs to network.build_query_string
• Does not canonicalise the link — host case, port, dot segments and existing escapes are left exactly as they arrived
• Does not fetch, resolve or check the link
• Does not accept a credential anywhere, including in the authority
• Does not generate a slug or shorten a link

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"marketing.utm_build","input":{"url":"https://acme.example.com/pricing","campaignParams":{"utm_source":"newsletter","utm_medium":"email"}}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("marketing.utm_build", {"campaignParams":{"utm_source":"newsletter","utm_medium":"email","utm_campaign":"spring sale"},"url":"https://acme.example.com/pricing?plan=team"});

Errors

Other limits

Limitations

• Invents no parameter value — no default source, medium or campaign id
• Does not sort the query; signing wants sorted keys and that belongs to network.build_query_string
• Does not canonicalise the link — host case, port, dot segments and existing escapes are left exactly as they arrived
• Does not fetch, resolve or check the link
• Does not accept a credential anywhere, including in the authority
• Does not generate a slug or shorten a link
• Adding an arbitrary query parameter that is not a campaign parameter
• Building a signed query where the key order has to be sorted
• Reading the campaign parameters back off a link

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "marketing.utm_build",
  "input": {
    "campaignParams": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "spring sale"
    },
    "url": "https://acme.example.com/pricing?plan=team"
  }
}

Examples

{
  "campaignParams": {
    "utm_source": "newsletter",
    "utm_medium": "email",
    "utm_campaign": "spring sale"
  },
  "url": "https://acme.example.com/pricing?plan=team"
}

{
  "encoding": {
    "spaceEncoding": "percent_20",
    "hexCase": "upper",
    "unreserved": "ALPHA DIGIT - . _ ~"
  },
  "skipped": [],
  "summary": {
    "reservedCharactersEncoded": 1,
    "urlLength": 108,
    "conflictCount": 0,
    "addedCount": 3,
    "queryParameterCount": 4
  },
  "added": [
    {
      "name": "utm_source",
      "position": 1,
      "valueLength": 10
    },
    {
      "name": "utm_medium",
      "position": 2,
      "valueLength": 5
    },
    {
      "name": "utm_campaign",
      "position": 3,
      "valueLength": 11
    }
  ],
  "url": "https://acme.example.com/pricing?plan=team&utm_source=newsletter&utm_medium=email&utm_campaign=spring%20sale",
  "conflicts": []
}

{
  "url": "https://acme.example.com/launch?utm_source=old-list",
  "conflictPolicy": "REPLACE",
  "campaignParams": {
    "utm_source": "spring-list"
  }
}

{
  "encoding": {
    "spaceEncoding": "percent_20",
    "hexCase": "upper",
    "unreserved": "ALPHA DIGIT - . _ ~"
  },
  "skipped": [],
  "summary": {
    "reservedCharactersEncoded": 0,
    "urlLength": 54,
    "conflictCount": 1,
    "addedCount": 1,
    "queryParameterCount": 1
  },
  "added": [
    {
      "name": "utm_source",
      "position": 0,
      "valueLength": 11
    }
  ],
  "url": "https://acme.example.com/launch?utm_source=spring-list",
  "conflicts": [
    {
      "name": "utm_source",
      "existingOccurrences": 1,
      "policyApplied": "REPLACE"
    }
  ]
}

Recommended use cases

• Tag a landing page for a newsletter or paid campaign with a stable, reproducible encoding
• Generate hundreds of campaign links from one template without a spreadsheet quietly mistyping utm_source
• Add a campaign parameter to a link that already carries a query, without touching what is there

Avoid for

• Adding an arbitrary query parameter that is not a campaign parameter
• Building a signed query where the key order has to be sorted
• Reading the campaign parameters back off a link

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags