Copy page

Tracking

Open Tracking

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

Code
curl -X PATCH https://api.lettermint.co/v1/routes/{route_id} \
  -H "Authorization: Bearer {team_api_token}" \
  -H "Content-Type: application/json" \
  -d '{"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

When a human-countable open is detected, Lettermint sends a message.opened webhook event. Machine, privacy proxy, and security scanner opens are excluded by default and are only sent to webhooks with Include machine events enabled.

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",
    "recipient": "user@example.com",
    "opened_at": "2025-08-08T20:17:00+00:00",
    "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 fields:

• first_open - true if this is the first time this recipient opened the email
• 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 default engagement metrics

See Bot Detection Field Values for classification and proxy_type values, plus reason_codes guidance.

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 images to protect user privacy:

• Apple Mail Privacy Protection - Loads all images automatically, regardless of whether the user opens the email
• Hey Email - Similar privacy-first image loading
• ProtonMail - Images loaded through proxy servers

Lettermint excludes identified privacy proxy opens from default metrics and webhooks. They remain available to opted-in webhooks and reporting requests that include machine activity.

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. Don't rely solely on opens - 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