# Track link engagement

> Create revocable links and read engagement from your server using Kismet.


Measure whether links in your emails or custom application have been opened. Create a link from your server, use its returned URL in your experience, and read its engagement through the same installation-scoped API.

> **Early access**
>
> This guide requires the tracked-links API extension and an SDK release containing `client.trackedLinks`. Existing npm versions may not include these methods. Request access before integrating.

## Set up access

Use a server credential with `links.write` to create or revoke links and `links.read` to inspect them. Register your destination's HTTPS origin on the installation. Keep this credential on your server; these methods are not available on the browser client.

```ts
import { createKismetClient } from '@kismet-tech/sdk/server';

const client = createKismetClient({
  baseUrl: 'https://api.ksmt.app/v1',
  collection: 'your-collection',
  apiKey: process.env.KISMET_SERVER_KEY!,
});

const link = await client.trackedLinks.create({
  destinationUrl: 'https://staging.example.com/welcome',
  channel: 'application',
  reference: 'welcome-cta',
  expiresAt: new Date(Date.now() + 60 * 60 * 1000).toISOString(),
  idempotencyKey: 'welcome-cta-link-0001',
});
// Render link.url as your call-to-action's href.
const result = await client.trackedLinks.get(link.id);
console.log(result.engagement.clicked, result.engagement.firstClickedAt);
// When the campaign ends:
await client.trackedLinks.revoke(link.id);
```

Persist the original request and reuse it unchanged when retrying creation. A changed request with the same idempotency key returns a conflict; recomputing the expiry would also change the request. Use an opaque campaign reference, not an email address or other personal information.

## Use in email or an application

For an email call-to-action, set `channel: 'email'` and use the returned URL in the message. Disable the sender's link rewriting for that URL so the recipient goes directly through Kismet. For a custom application, use `channel: 'application'` for links such as an article or campaign call-to-action.

[Configured offer emails](https://developers.kismet.travel/guides/test-offer-email.md) create their Kismet tracking link automatically. The offer flow validates its provider destination separately; callers cannot use the general link API to redirect to arbitrary third-party origins.

## Understand the result

`clicked` means at least one redirect was observed. `firstClickedAt` records the first observation; repeated visits do not create additional unique-click records. Email security scanners can follow links, so this is not proof of a human visit. It is also not proof of redemption, payment, booking, consent, or authentication.

TEST links expire within 24 hours; LIVE links expire within 30 days. Revoked, expired, or inactive-installation links stop resolving. Inspecting a link returns its destination origin, not its full destination URL. Keep your original destination in your own application if needed.

Do not wrap sign-in, verification, or unsubscribe links. These links serve a different purpose and must retain their own security and consent behavior.

## API reference

- [Create a tracked link](https://developers.kismet.travel/api/reference/create-developer-tracked-link.md)
- [Read a tracked link](https://developers.kismet.travel/api/reference/get-developer-tracked-link.md)
- [Revoke a tracked link](https://developers.kismet.travel/api/reference/revoke-developer-tracked-link.md)