# 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.

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.

> **Note**
>
> **Link tracking requires access.** In [Opt-in features](https://docs.polymorfa.com/teams/opt-in-features), a team owner or
> admin selects **Link tracking**, then **Join**, reviews the terms and selects
> **Accept and join**. The campaign builder's **Compose** step links there with a
> **Preview** badge. Until your team has joined, requests
> that set tracked links, launch a campaign with tracked links, or read link
> opens return `403 feature_unavailable`.

## 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.

## Add tracked links to a campaign

**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.

```bash 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 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 `POST /platform/campaigns` or
`PATCH /platform/campaigns/{campaignId}`.

*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.

## Read link opens

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:**

```bash cURL
curl "https://api.polymorfa.com/messaging/projects/$PROJECT_SLUG/campaigns/$CAMPAIGN_ID/links" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript 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 }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `uniqueOpens` | Recipients who opened the link at least once. |
| `totalOpens` | Every recorded open, including repeat opens. |

The Platform API returns the same list from
`GET /platform/campaigns/{campaignId}/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](https://docs.polymorfa.com/api/events#campaigns-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

- [Send a campaign](https://docs.polymorfa.com/campaigns/send)
- [Campaign events](https://docs.polymorfa.com/api/events#campaigns-events)
- [Drip sequences](https://docs.polymorfa.com/campaigns/drip-sequences)
