Tracking

Track email opens, link clicks, and recipient engagement. PostStack detects client applications, operating systems, and geographic data from tracking events.

Open Tracking

When open tracking is enabled on a domain, PostStack inserts an invisible 1x1 pixel into HTML emails. When the recipient loads the image, an email.opened event is recorded.

// Enable open tracking on a domain
await poststack.domains.update(12, { // numeric domain id (REST also accepts dom_…)
  open_tracking: true,
});

Click Tracking

When click tracking is enabled, PostStack rewrites links in your HTML emails to pass through a tracking redirect. When a recipient clicks a link, an email.clicked event is recorded with the original URL, then the recipient is redirected to the destination.

// Enable click tracking on a domain
await poststack.domains.update(12, {
  click_tracking: true,
});

Tracking Domains

By default, the tracking pixel and rewritten links use PostStack's own domain (e.g. https://poststack.dev/api/tracking/click/…). You can configure a custom tracking domain for branded links. Add a CNAME record pointing your tracking subdomain to PostStack:

// Set a custom tracking domain
await poststack.domains.update(12, {
  tracking_domain: 'track.yourdomain.com',
});

Client and OS Detection

PostStack parses the User-Agent and IP of open and click events to detect the recipient's email client, operating system and approximate location. The parsed data powers the dashboard analytics (provider, device and geography breakdowns); the webhook payload carries the raw values so you can run your own parsing:

{
  "type": "email.opened",
  "created_at": "2026-03-23T10:01:15.000Z",
  "data": {
    "email_id": "em_abc123def456ghi789",
    "ip_address": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15"
  }
}

The approximate location (country, region, city) is looked up locally on our own servers against the DB-IP Lite database; recipient IP addresses are never sent to a third-party geolocation service. IP geolocation by DB-IP (CC BY 4.0).

email.clicked adds the original destination URL:

{
  "type": "email.clicked",
  "created_at": "2026-03-23T10:02:40.000Z",
  "data": {
    "email_id": "em_abc123def456ghi789",
    "url": "https://app.example.com/dashboard",
    "ip_address": "203.0.113.24",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15"
  }
}

Tracking Events

Tracking generates the following webhook events:

Disabling Tracking Per Email

You can disable tracking for individual emails even when domain-level tracking is enabled. This is useful for transactional emails like password resets:

await poststack.emails.send({
  from: 'noreply@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Reset your password',
  html: '<p>Click <a href="https://app.example.com/reset?token=...">here</a> to reset.</p>',
  tracking: {
    opens: false,
    clicks: false,
  },
});