Track link engagement

View .md

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.

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.

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

Track link engagement

Set up access

Use in email or an application

Understand the result

API reference