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.

typescript

// Enable open tracking on a domain
await poststack.domains.update('dom_abc123def456', {
  open_tracking: true,
});

Open tracking relies on image loading and may not fire if the recipient's email client blocks remote images. Open rates should be treated as approximate.

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.

typescript

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

Tracking Domains

By default, tracking links use the PostStack domain (e.g., track.poststack.dev). You can configure a custom tracking domain for branded links. Add a CNAME record pointing your tracking subdomain to PostStack:

Type	Name	Value
`CNAME`	`track.yourdomain.com`	`track.poststack.dev`

typescript

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

Client and OS Detection

PostStack parses the User-Agent from open and click events to detect the recipient's email client and operating system. This data is included in email events and webhook payloads:

json

{
  "type": "email.opened",
  "timestamp": "2026-03-23T10:01:15.000Z",
  "data": {
    "email_id": "em_abc123def456ghi789",
    "client": {
      "name": "Apple Mail",
      "type": "desktop",
      "os": "macOS"
    },
    "location": {
      "country": "US",
      "region": "California",
      "city": "San Francisco"
    }
  }
}

Tracking Events

Tracking generates the following webhook events:

Event	Description
`email.opened`	Recipient opened the email (tracking pixel loaded)
`email.clicked`	Recipient clicked a tracked link in the email
`email.unsubscribed`	Recipient clicked the unsubscribe link in the email

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:

typescript

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: {
    open: false,
    click: false,
  },
});