urldn-utm-validator

Catch broken UTM parameters before you ship a campaign — not after you notice a hole in your analytics.

urldn-utm-validator checks any URL's utm_source, utm_medium, utm_campaign, utm_term, and utm_content parameters for the mistakes that quietly wreck attribution: missing required params, inconsistent casing, duplicate keys, unencoded spaces, and non-standard medium values. Use it as a CLI in your terminal or CI pipeline, or import it directly in Node.

Why this exists

A single mistyped utm_medium — Email instead of email — splits one channel into two rows in every dashboard downstream. Multiply that across a marketing team pasting links into Google Ads, Mailchimp, and social schedulers by hand, and campaign reporting quietly rots. This tool catches that class of bug in under a second, before the link goes out.

It's maintained by the team behind URLdn, a link intelligence platform that reads shortened-link analytics with an AI layer instead of raw dashboards — this validator is the free, standalone piece of that same problem space.

Install

npm install -g urldn-utm-validator

Or run it once without installing:

npx urldn-utm-validator "https://example.com?utm_source=newsletter&utm_medium=email&utm_campaign=q3-launch"

CLI usage

utm-check "https://example.com?utm_source=Newsletter&utm_medium=email&utm_campaign=spring sale"

URL:  https://example.com?utm_source=Newsletter&utm_medium=email&utm_campaign=spring sale
Score: 65/100

! [utm_source] "utm_source=Newsletter" contains uppercase letters. Analytics tools
  treat casing as distinct values, splitting one channel into two rows.
! [utm_campaign] "utm_campaign=spring sale" contains a raw space. Use hyphens
  instead, e.g. "spring-sale" not "spring sale".

Pipe a URL in instead of passing it as an argument:

echo "https://example.com?utm_source=fb" | utm-check

Machine-readable output for scripts and CI:

utm-check "https://example.com" --json

Fail CI on warnings too, not just hard errors:

utm-check "$URL" --strict

Options

| Flag | Description | |---|---| | --json | Print a machine-readable JSON report instead of formatted text | | --strict | Exit non-zero on warnings, not only on errors | | -h, --help | Show usage |

Exit code is 0 when the URL has no errors, 1 otherwise — safe to drop into a pre-commit hook or CI step that validates campaign links before a marketing PR merges.

Node API

import { validateUtm } from "urldn-utm-validator";

const result = validateUtm(
  "https://example.com?utm_source=Newsletter&utm_medium=email&utm_campaign=spring sale"
);

console.log(result.score);  // 65
console.log(result.valid);  // true (no hard errors, only warnings)
console.log(result.issues); // array of { level, param, message }
console.log(result.params); // parsed utm_source / utm_medium / utm_campaign / utm_term / utm_content

validateUtm(url: string): ValidationResult

interface ValidationResult {
  url: string;
  valid: boolean;      // false if any "error"-level issue is present
  score: number;        // 0-100 quality score
  params: UtmParams;     // the five parsed UTM values, or null if absent
  issues: UtmIssue[];   // level: "error" | "warning" | "info"
}

What it checks

• Required params — flags a missing utm_source, utm_medium, or utm_campaign
• Duplicate params — same key appearing twice in the query string
• Casing consistency — uppercase letters that fragment reporting (Facebook vs facebook)
• Unencoded spaces — raw spaces or + in a value instead of hyphens
• Non-standard medium — soft warning when utm_medium doesn't match common values (cpc, email, social, organic, referral, affiliate, display, sms, newsletter, ...)
• Domain-as-source — flags utm_source values that look like a full domain instead of a short label

This is a linter, not a spec enforcer — the "info"-level checks are suggestions, not failures, since UTM conventions vary by team.

Related

If you're shortening the links you're tagging, URLdn pairs a short link with an AI analyst that reads your click data directly and answers questions about it in plain English — built for teams without a dedicated data analyst on staff.

Contributing

Issues and PRs welcome. Keep the dependency footprint minimal — this package intentionally has one runtime dependency (picocolors) and no build framework beyond tsc.

git clone https://github.com/urldn/urldn-utm-validator.git
cd urldn-utm-validator
npm install
npm run build
node dist/cli.js "https://example.com?utm_source=test&utm_medium=cpc&utm_campaign=test"

License

MIT © URLdn