Tracking

Tracking tells you what happens after an email is delivered. Open tracking records when a recipient views your message, and click tracking records when they interact with links inside it. Together, these signals help you measure engagement, identify content that resonates, and trigger follow-up workflows based on recipient behavior. Lettr enables both by default, but you can disable either on a per-email basis for privacy-sensitive messages.

Default Tracking

By default, Lettr tracks opens and clicks for all emails. No additional configuration is needed — tracking is active as long as you send HTML content:

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Newsletter',
  html: '<p>Check out our <a href="https://example.com">website</a>!</p>'
  // Open and click tracking enabled by default
});

Customize Tracking Options

When sending through the API or an SDK, you can override the default tracking behavior on a per-email basis using the options object. This is useful for privacy-sensitive emails like password resets or data exports where tracking would be inappropriate:

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Private Message',
  html: '<p>This is a private message.</p>',
  options: {
    open_tracking: false,
    click_tracking: false
  }
});

SMTP Tracking Headers

When sending over SMTP, add these message headers to disable open and click tracking:

X-Lettr-Track-Opens: false
X-Lettr-Track-Clicks: false

Header	Accepted values	Default when omitted
`X-Lettr-Track-Opens`	`true` or `false`	`true`
`X-Lettr-Track-Clicks`	`true` or `false`	`true`

The headers work independently. For example, setting only X-Lettr-Track-Opens: false disables the open tracking pixel while keeping click tracking enabled. Header names and values are case-insensitive, and surrounding whitespace is ignored. Each setting applies to every recipient of that message. It does not change the defaults for later messages, even on the same SMTP connection. Lettr consumes these control headers; they are not included in the delivered email. Add each header at most once. An empty value, a value other than true or false, or a duplicate header causes Lettr to reject the message after DATA with 554 5.6.0. The error identifies the invalid header. Correct it before retrying; the rejected message is not sent. See the Laravel example or PHPMailer example for adding these headers with your mail library.

X-MSYS-API is a SparkPost-specific header, not a standard SMTP setting. Lettr does not support it. When migrating, use the two X-Lettr-* headers above to control tracking.

Disabling tracking prevents Lettr from adding its open tracking pixel or rewriting links for that message. It does not remove tracking pixels or tracking URLs already present in the HTML you submit, or change emails already sent. Delivery and bounce events remain available.

How Open Tracking Works

Lettr inserts a tiny invisible image (tracking pixel) into your HTML emails. When the recipient’s email client loads images, the open is recorded.

Open tracking requires HTML content. Plain text emails cannot be tracked for opens. Some email clients block images by default, which may result in under-reported open rates.

How Click Tracking Works

Lettr rewrites links in your email to route through our tracking servers. When a recipient clicks a link:

The click is recorded with timestamp and link URL
The recipient is immediately redirected to the original destination

<!-- Original link in your email -->
<a href="https://example.com/product">View Product</a>

<!-- Becomes (with click tracking enabled) -->
<a href="https://track.lettr.com/c/abc123">View Product</a>

Custom Tracking Domain

By default, tracking links use Lettr’s domain (e.g., track.lettr.com). Configuring a custom tracking domain (e.g., track.yourdomain.com) improves deliverability because links match your sending domain, and it builds trust with recipients who see a familiar domain in link previews:

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Newsletter',
  html: '<p>Click <a href="https://example.com">here</a>!</p>',
  options: {
    click_tracking: true
  }
});

Links will use your configured tracking domain (e.g., track.yourdomain.com) if set up in your domain settings. A custom tracking domain changes the hostname used for tracking; it does not enable or disable tracking. There is no sending-domain-wide tracking toggle. Use the per-message API options or SMTP headers to disable tracking. To disable it for every message, apply those settings in your application’s shared mail configuration or message-building code.

Set Up Tracking Domain

Learn how to configure a custom tracking domain

Transactional Flag

The transactional option signals to Lettr how to handle the email for deliverability purposes. Transactional emails (triggered by a user action) are typically sent with higher priority and are less likely to be filtered by receiving mail servers:

await lettr.emails.send({
  from: 'you@example.com',
  to: ['recipient@example.com'],
  subject: 'Password Reset',
  html: '<p>Click here to reset your password...</p>',
  options: {
    transactional: true  // Default is true
  }
});

Transactional emails (password resets, order confirmations) typically have higher deliverability than marketing emails.

Tracking Options Reference

Option	Type	Default	Description
`open_tracking`	boolean	`true`	Track when emails are opened
`click_tracking`	boolean	`true`	Track when links are clicked
`transactional`	boolean	`true`	Mark as transactional email

Privacy Considerations

Some emails should not be tracked. Data exports, security notifications, and emails sent in jurisdictions with strict privacy laws (such as GDPR) may require tracking to be disabled. Disable both open and click tracking for these messages:

// For privacy-sensitive emails
await lettr.emails.send({
  from: 'you@example.com',
  to: ['privacy-conscious@example.com'],
  subject: 'Your Data Export',
  html: '<p>Here is your requested data export.</p>',
  options: {
    open_tracking: false,
    click_tracking: false
  }
});

Viewing Tracking Data

Tracking data is delivered in real time through webhooks. Subscribe to the engagement.open and engagement.click events, then read them from the payload. The request body is an array of events, and each event is wrapped in a msys envelope keyed by category. Read the category key first, then the inner object — its type is the short event name (open, click), not the namespaced name you subscribed with:

app.post('/webhooks/lettr', express.json(), (req, res) => {
  // Acknowledge first, then process — slow handlers cause retries.
  res.sendStatus(200);

  for (const event of req.body) {
    const category = Object.keys(event.msys ?? {})[0];
    const data = category ? event.msys[category] : null;
    if (!data) continue;

    if (data.type === 'open') {
      console.log('Email opened:', data.transmission_id, data.rcpt_to);
    }

    if (data.type === 'click') {
      console.log('Link clicked:', data.transmission_id, data.rcpt_to);
    }
  }
});

You can also view aggregate tracking data in the Analytics dashboard.

Analytics

Learn more about viewing and analyzing tracking data

Documentation

Quickstart

Learn

Integrations

Resources

Default Tracking

Customize Tracking Options

SMTP Tracking Headers

How Open Tracking Works

How Click Tracking Works

Custom Tracking Domain

Set Up Tracking Domain

Transactional Flag

Tracking Options Reference

Privacy Considerations

Viewing Tracking Data

Analytics

​Default Tracking

​Customize Tracking Options

​SMTP Tracking Headers

​How Open Tracking Works

​How Click Tracking Works

​Custom Tracking Domain

Set Up Tracking Domain

​Transactional Flag

​Tracking Options Reference

​Privacy Considerations

​Viewing Tracking Data

Analytics

Default Tracking

Customize Tracking Options

SMTP Tracking Headers

How Open Tracking Works

How Click Tracking Works

Custom Tracking Domain

Transactional Flag

Tracking Options Reference

Privacy Considerations

Viewing Tracking Data