Skip to content
Shortcut: /, ⌘K or Ctrl+K

Track campaign links

Give each campaign recipient a short link, count link opens per link, and receive the first open of each link as a webhook event.

View as Markdown

Link tracking replaces a link in a campaign message with a short link that is different for every recipient. When a recipient opens it, Polymorfa counts the open and redirects them to your destination.

What you can track#

  • Campaigns sent from linked-device numbers or test numbers. A campaign that would send from Cloud API Numbers is refused at launch, because an approved template keeps its approved links.
  • Up to five links per campaign. Each link has a key and a destination url.
  • key is 1 to 32 lowercase letters, digits, or underscores, unique within the campaign.
  • url is an absolute https URL with a public domain name, at most 2,048 characters. User names, passwords, IP addresses, and local network names such as localhost or names ending in .local or .internal are refused.

Console

  1. In the campaign builder's Compose step, open Tracked links.
  2. Select Add link, then enter a key and a destination URL.
  3. Paste the placeholder the panel shows, such as {{link:offer}}, into your message.

API

Send trackedLinks when you create or update a draft, and write {{link:<key>}} where the link belongs in the message.

cURL
curl -X PATCH "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackedLinks": [
      { "key": "offer", "url": "https://example.com/spring-sale" }
    ]
  }'
TypeScript
await messaging.campaigns.update("<project-slug>", campaignId, {
  trackedLinks: [{ key: "offer", url: "https://example.com/spring-sale" }],
});

On the Platform API, send the same field to API Create campaign or API Update campaign.

TypeScript:

create and update accept trackedLinks.

A message such as Hi {{first_name}}, see the sale: {{link:offer}} reaches each recipient with their own short link in place of {{link:offer}}. The placeholder works anywhere the campaign's message text does, including a template's body and URL buttons.

Campaign reads return trackedLinks, an empty array when the campaign tracks none. Send null or [] to remove the links; removing them does not need the beta.

Tracked links change only while the campaign is a draft, including while it waits for a scheduled start. After sending starts, a change returns 409. A launched campaign waiting for its start must still define every {{link:<key>}} its messages use.

Launch checks#

Launch returns 400 invalid_parameter with param set to trackedLinks when:

  • a message uses a {{link:<key>}} the campaign does not define, so a placeholder is never sent as plain text; or
  • the campaign has tracked links and would send from Cloud API Numbers.

What recipients receive#

Each recipient gets a short link on the API host for every tracked link their message uses:

Text
https://api.polymorfa.com/l/<token>
  • Opening it returns a temporary redirect to the destination the link had when the message was sent. A later change to the campaign never moves a sent link.
  • The redirect sets no cookies and sends no referrer.
  • A link stops working 90 days after Polymorfa creates it, when the message is prepared for sending. An expired or unknown link returns 404.
  • When a send is retried, the retry carries a new short link. The earlier link keeps working until it expires.

While your team has the beta, GET requests for a short link count as opens, except known link previews, crawlers, security scanners and requests marked as prefetch. These requests still redirect, but do not count or end a drip. HEAD requests never count. Detection is best effort: unknown or disguised automated fetches can still count, so an open is not proof that a person clicked.

Console

Open the campaign's Analytics page. Link opens lists each tracked link with its unique and total opens.

API

cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/links" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
TypeScript
const links = await messaging.raw.request({
  method: "GET",
  path: `/messaging/projects/<project-slug>/campaigns/${campaignId}/links`,
});
console.log(links.data);

TypeScript:

The SDK has no method for the link open report yet, so the example calls it with raw.request.

The response:

JSON
{
  "success": true,
  "data": [
    { "key": "offer", "url": "https://example.com/spring-sale", "uniqueOpens": 412, "totalOpens": 655 }
  ]
}
FieldMeaning
uniqueOpensRecipients who opened the link at least once.
totalOpensEvery recorded open, including repeat opens.

The Platform API returns the same list from API Get campaign links. Reading needs campaigns:read.

Receive the first open as a webhook#

Subscribe a project webhook to campaign.recipient_link_opened. Polymorfa sends it once per recipient and tracked link, at the first open.

JSON
{
  "id": "019b2345-5555-7555-8555-555555555555",
  "session": "sales-1",
  "timestamp": "2026-10-05T14:20:00.000Z",
  "event": "campaign.recipient_link_opened",
  "payload": {
    "campaignId": "019b2345-3333-7333-8333-333333333333",
    "recipientId": "019b2345-4444-7444-8444-444444444444",
    "linkKey": "offer",
    "openedAt": 1791190800
  }
}

session names the number that sent the recipient's message. openedAt uses Unix seconds. The event carries no phone number, link, destination, IP address, or user agent. Use recipientId with the campaign's recipient list to join it to your own records. See Campaign events for delivery rules. The TypeScript SDK types the payload as CampaignRecipientLinkOpenedPayload.

Privacy and retention#

  • Polymorfa does not store a recipient's IP address or user agent with an open.
  • Open counts are kept for 400 days after a recipient's first open of a link.
  • Deleting a campaign or a recipient deletes its short links and opens.

Leaving the beta#

When your team withdraws from the beta or the beta becomes unavailable to it:

  • Messages sent afterwards carry each link's original destination, without tracking.
  • Short links already sent keep redirecting until they expire, without recording opens or sending events.
  • Setting tracked links, launching a campaign with tracked links, and reading link opens return 403 feature_unavailable. Removing tracked links still works.

See also#