# 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.

```html
<!-- 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

```bash
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}'
```

:::note
Open tracking is only available for **transactional** and **broadcast** routes. Inbound routes cannot have tracking enabled.
:::

### 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`:

```json
{
  "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:

```text
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.

```json
{
  "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](/platform/emails/tracking/introduction#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**](/platform/emails/tracking/click-tracking) - Track link clicks for deeper engagement insights
- [**Webhook Events**](/platform/webhooks/events) - Full payload reference for tracking events