Copy page

Tracking

Open tracking

Enable open tracking to record when an email client loads the tracking pixel in an HTML message.

How it works

When open tracking is enabled for a route, Lettermint automatically injects a transparent 1x1 tracking pixel into your HTML emails. The pixel is inserted just before the closing </body> tag.

Code
<!-- Your email content -->
<img src="https://t.ltrmnt.com/o/{tracking_token}"
     width="1" height="1"
     style="display:block;width:1px;height:1px;border:0;"
     alt="">
</body>

When the recipient's email client renders the email and loads images, the pixel request is stored as a tracking observation. Lettermint classifies the observation before it is promoted into customer-visible events, status, webhooks, and default metrics.

Enabling open tracking

Via dashboard

1. Navigate to your project
2. Go to Routes and select your transactional or broadcast route
3. In Route Settings, enable Track Opens
4. Save your changes

Via API

Use the route update method shown in Tracking with this settings payload:

Code
{
  "settings": {
    "track_opens": true
  }
}

Per-email override

You can override the route's open tracking setting for a single email. This is useful for sensitive transactional messages that use a tracked route, or for one-off emails where you want to enable open tracking without changing the route default.

API sends use settings.track_opens:

Code
{
  "from": "sender@yourdomain.com",
  "to": ["recipient@example.com"],
  "subject": "Security code",
  "html": "<p>Your code is 123456.</p>",
  "settings": {
    "track_opens": false
  }
}

SMTP sends use the Lettermint override header:

Code
X-LM-Override-Track-Opens: false

The override applies only to that email and takes precedence over the selected route's Track Opens setting.

Bot detection

Many email opens are not from actual humans viewing the email. Email clients, security tools, and privacy features can trigger open events automatically. Lettermint detects these automated interactions to give you accurate engagement data.

Webhook payload

Lettermint sends message.opened for human-countable opens and supported privacy opens. Security scanners, previews, and generic bots require Include machine events.

Code
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event": "message.opened",
  "timestamp": "2025-08-08T20:17:00.000Z",
  "data": {
    "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subject": "Your order has shipped",
    "metadata": {
      "X-Order-ID": "order-12345"
    },
    "tag": "shipping",
    "tags": [
      {"name": "__lettermint_tag", "value": "shipping"},
      {"name": "environment", "value": "production"}
    ],
    "recipient": "user@example.com",
    "opened_at": "2025-08-08T20:17:00+00:00",
    "tracking_event_id": "0198a5bd-6008-7d91-a532-635dc95f4371",
    "classification_revision": 1,
    "first_open": true,
    "device_type": "desktop",
    "client_type": "browser",
    "client_name": "Chrome",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "bot": {
      "detected": false,
      "probability": 0,
      "classification": "genuine",
      "proxy_type": null,
      "reason_codes": [],
      "machine": false,
      "counts_for_metrics": true
    },
    "engagement": {
      "event_id": "0198a5bd-6008-7d91-a532-635dc95f4371",
      "revision": 1,
      "request_actor": "human",
      "engagement_state": "high_confidence_human",
      "time_basis": "direct_observation",
      "human_open_time_known": true,
      "observed_open": true,
      "human_open": true,
      "privacy_open": false,
      "inferred": false
    }
  }
}

Engagement fields:

• tracking_event_id - Stable ID for this tracking observation. Use it with classification_revision to process later updates.
• classification_revision - Revision number for this tracking event. A higher number replaces a lower number for the same tracking_event_id.
• engagement - Optional engagement conclusion. It separates observed, human, privacy, and inferred engagement. It can also contain privacy_fetch_at, engagement_confirmed_at, and human_open_time_known.
• first_open - true if this is the first time this recipient opened the email
• first_observed_open - true for the first human or supported privacy open observation
• device_type - Device category: desktop, mobile, or tablet
• client_type - Client category: browser, email_client, etc.
• client_name - Specific client name: Chrome, Safari, Outlook, etc.

Bot detection fields:

• bot.detected - true if the open appears automated
• bot.probability - Confidence score from 0-100 (higher = more likely a bot)
• bot.classification - Source classification such as genuine, privacy_proxy, security_scanner, or generic_bot
• bot.proxy_type - Known proxy family when applicable, otherwise null
• bot.reason_codes - Machine-readable reasons behind the classification
• bot.machine - true when the open is classified as machine, privacy, or security activity
• bot.counts_for_metrics - Whether the open contributes to human-open metrics. Privacy opens use separate observed and privacy metrics.
• bot.counts_for_status - Whether the event can change the message status
• bot.webhook_eligible - Whether the event is eligible for a default webhook

Privacy inference revisions

A supported privacy fetch first creates a message.opened event at revision 1. If a later high-confidence click confirms human engagement, Lettermint sends revision 2 of the open event. The revised event keeps the same tracking_event_id, opened_at, and engagement.privacy_fetch_at values. Its engagement.engagement_confirmed_at value contains the click time. Its engagement.human_open_time_known value is false because a privacy proxy hides the human-open time.

The related message.clicked event has its own tracking_event_id and starts at revision 1. Store the highest classification_revision for each tracking_event_id.

See Bot Detection Field Values for the stable classification contract and guidance for open diagnostic strings.

Limitations

HTML emails only

Open tracking requires HTML content. The tracking pixel cannot be added to:

• Plain-text only emails
• Emails where the recipient views only the text part

Token expiration

Tracking tokens expire 30 days after the email is sent. Opens after this period are not recorded. This protects recipient privacy and reduces long-term data storage.

Privacy proxies

Some email clients pre-fetch or relay images to protect user privacy:

• Apple relay - The relay IP cannot separate Mail Privacy Protection from Hide IP Address. Lettermint records an ambiguous privacy open.
• Proton Mail - Verified delivery-prefetch activity is a privacy open.
• HEY and Fastmail - Their documented proxies fetch when the user displays the message, so Lettermint records a likely-human proxy open.
• DuckDuckGo and Superhuman - These clients can remove or block tracking pixels. Lettermint does not create an open when no request exists.

Observed opens are the unique union of human opens and supported privacy opens. Human and privacy counts remain separate. A later high-confidence click can confirm engagement for an Apple or Proton privacy fetch, but it cannot reveal the real human-open time.

Image blocking

Some recipients configure their email clients to block images by default. These opens will only be recorded if the recipient explicitly loads images.

Best practices

1. Do not use opens as your only signal - Click tracking provides stronger engagement signals
2. Consider privacy - Be transparent with recipients about tracking in your privacy policy
3. Monitor trends - Individual open rates vary; focus on aggregate trends over time

Next steps

• Click Tracking - Track link clicks for deeper engagement insights
• Webhook Events - Full payload reference for tracking events