# Email Tracking ## Overview Email tracking lets you measure engagement by detecting when recipients open your emails and click links. Tracking is configured at the route level, giving you granular control over which emails are tracked. **Key features:** - **Open tracking** — Know when recipients view your emails - **Click tracking** — Track which links recipients click - **Custom tracking domains** — White-label tracking links with your own domain (Pro) - **Bot detection** — Filter out automated opens and clicks from analytics - **Webhook events** — Receive real-time notifications for engagement ## How It Works ### Open Tracking When open tracking is enabled, Lettermint automatically injects a transparent 1x1 pixel image before the closing `` tag of HTML emails. When the recipient's email client loads this image, we store the request as a tracking observation and classify it before it contributes to customer-visible events and metrics. ### Click Tracking When click tracking is enabled, Lettermint rewrites links in your email to route through our tracking domain (`t.ltrmnt.com`). When a recipient clicks a link: 1. The request hits our tracking server 2. We store the click observation with timestamp and link URL 3. The recipient is immediately redirected to the original destination 4. The observation is classified before it contributes to customer-visible events and metrics Both tracking methods use secure, signed tokens that expire after **30 days** to protect recipient privacy. ## Configuration Tracking is configured per-route in your project settings. This allows you to: - Enable tracking only for marketing/broadcast routes - Keep transactional emails tracking-free for simplicity - Test tracking on specific routes before wider rollout ### Per-Email Overrides Route settings are the default for every email sent through that route. You can override open and click tracking for a single email without changing the route configuration. For API sends, add a `settings` object to the email payload: ```json { "from": "sender@yourdomain.com", "to": ["recipient@example.com"], "subject": "Your receipt", "html": "

Thanks for your order.

", "settings": { "track_opens": false, "track_clicks": false } } ``` For SMTP sends, add Lettermint override headers: ```text X-LM-Override-Track-Opens: false X-LM-Override-Track-Clicks: false ``` These overrides apply only to the email that includes them and take precedence over the selected route's tracking settings. ### Enabling via Dashboard 1. Navigate to your project in the dashboard 2. Go to **Routes** and select your route 3. In **Route Settings**, toggle **Track Opens** and/or **Track Clicks** 4. Save your changes ### Enabling via API Use the Team API to configure tracking programmatically: ```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, "track_clicks": true }' ``` ## Privacy & Compliance Lettermint is designed with privacy in mind. Important considerations for GDPR and other privacy regulations: - **Tracking disabled by default** - You must explicitly enable tracking per route - **Limited raw signal retention** - Raw tracking observations retain exact IP addresses, user agents, and request headers for up to 28 days for classification and abuse analysis, then minimize exact raw signals while preserving IP hashes and classification metadata - **Privacy policy disclosure** - Mention email tracking in your privacy policy - **Recipient opt-out** - Consider offering recipients a way to opt out of tracked emails - **Marketing consent** - For marketing/broadcast emails, ensure you have explicit opt-in consent before enabling tracking ## Bot Detection Not all opens and clicks come from humans. Email security scanners, link preview bots, and privacy proxies can trigger tracking requests. Lettermint classifies these observations and excludes machine, privacy, and security activity from default engagement metrics, message status updates, event history, and webhooks. Each tracking event includes: - `bot.detected` - Boolean indicating if the interaction appears automated - `bot.probability` - Confidence score (0-100) for the bot detection - `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` - Whether the event is classified as non-human machine, privacy, or security activity - `bot.counts_for_metrics` - Whether the event contributes to default engagement metrics - `first_open` / `first_click` - Whether this is the first time this recipient engaged - `device_type` - Device category: `desktop`, `mobile`, `tablet` - `client_type` - Client category: `browser`, `email_client`, etc. - `client_name` - Specific client: `Chrome`, `Safari`, `Outlook`, etc. ### Bot Detection Field Values The `bot` object uses the same fields for `message.opened` and `message.clicked` webhook payloads. | Field | Values | Description | | --- | --- | --- | | `detected` | `true`, `false` | `true` when Lettermint detected automated, privacy, preview, scanner, or otherwise suspicious activity. | | `probability` | Integer from `0` to `100` | Bot probability score. Higher values are more likely to be automated or non-human activity. | | `classification` | See classification values below | The primary classification assigned by the tracking classifier. | | `proxy_type` | See proxy values below, or `null` | Known proxy family when the signal matches a supported proxy source. | | `reason_codes` | List of strings | Diagnostic labels that provide additional classification context. The list can be empty. | | `machine` | `true`, `false` | `true` when the event is excluded from default human engagement metrics and default webhooks as machine, privacy, preview, scanner, or suspicious activity. | | `counts_for_metrics` | `true`, `false` | `true` when the event contributes to default opens, clicks, statuses, and engagement reporting. | #### Classification Values | Value | Meaning | Counts for default metrics | | --- | --- | --- | | `genuine` | Human-countable open or click. | Yes | | `image_proxy` | Known mailbox image proxy activity that is treated as human-countable engagement. | Yes | | `privacy_proxy` | Privacy-preserving proxy or prefetch activity. | No | | `security_scanner` | Corporate, mailbox, or security scanning activity. | No | | `link_preview_bot` | Link preview generators from chat, social, or messaging apps. | No | | `generic_bot` | Generic crawler, automation, synthetic client, or scripted activity. | No | | `suspicious` | Activity that is not confidently human and is excluded from default engagement metrics. | No | | `unverified_click` | Reserved countable click classification for browser-like clicks that need extra audit context. | Yes | #### Proxy Type Values | Value | Meaning | | --- | --- | | `gmail` | Gmail image proxy. | | `yahoo` | Yahoo Mail image proxy. | | `apple_mpp` | Apple Mail Privacy Protection proxy activity. | | `apple_private_relay` | Apple Private Relay or Apple relay network activity. | | `null` | No known proxy family was detected. | #### Reason Code Guidance Reason codes are opaque diagnostic labels for troubleshooting and support. They are not a stable public enum, and Lettermint may add, remove, rename, or combine codes as the classifier improves. Build integrations against `bot.machine`, `bot.counts_for_metrics`, `bot.detected`, `bot.classification`, and `bot.proxy_type`. You can store or display `reason_codes` for diagnostics, but should not depend on exact values for customer-facing logic. See the [Open Tracking](/platform/emails/tracking/open-tracking) and [Click Tracking](/platform/emails/tracking/click-tracking) pages for detailed bot detection information. ## Webhook Events When human-countable tracking events occur, Lettermint sends webhook notifications: - **`message.opened`** - Recipient opened the email - **`message.clicked`** - Recipient clicked a link Configure webhooks on your route to receive these events. Machine, privacy proxy, and security scanner observations are excluded by default and are only sent when the webhook has **Include machine events** enabled. See [Webhook Events](/platform/webhooks/events) for payload details. ## Viewing Metrics Track engagement metrics in your dashboard: 1. Navigate to your project 2. View route-level or message-level analytics 3. See open rates, click rates, and engagement over time Bot, privacy proxy, and scanner interactions are filtered from aggregate metrics by default, giving you accurate human engagement data. API reporting can include machine activity with `include_machine=true`. ## Limitations - **HTML emails only** - Open tracking requires HTML content; plain-text emails cannot be tracked - **Token expiration** - Tracking tokens expire after 30 days; events after expiration are not recorded - **Privacy proxies** - Some email clients (Apple Mail Privacy Protection, Hey) pre-fetch images; identified privacy opens are excluded from default metrics - **Corporate security** - Link scanners may pre-click links, though bot detection filters most of these ## FAQ
Does tracking affect email deliverability? Both tracking methods can have minor deliverability implications: - **Click tracking** - Rewritten links route through our tracking domain (`t.ltrmnt.com`). Some aggressive spam filters flag redirect links, though impact is minimal for established senders. - **Open tracking** - The 1x1 pixel can trigger image preloading warnings in some clients, particularly Gmail. This may slightly increase spam filter scrutiny. - **Domain reputation** - Our tracking domain maintains high deliverability standards to minimize impact. For critical transactional emails (password resets, 2FA codes), consider keeping tracking disabled to maximize deliverability.
Should I enable tracking for transactional emails? It depends on your use case: - **Marketing/broadcast emails** - Yes, tracking provides valuable engagement metrics - **Order confirmations, receipts** - Usually safe to enable - **Password resets, 2FA, security alerts** - Consider disabling to ensure maximum deliverability Use route-level configuration to enable tracking selectively.
Will recipients see the tracking domain in links? Yes, when hovering over links, recipients will see `t.ltrmnt.com` instead of your destination URL. This is standard for email tracking. The redirect is instant, so user experience is not affected.
Can I use my own domain for tracking links? Yes! Custom tracking domains are available on Pro plans. You can use your own subdomain (e.g., `track.yourdomain.com`) instead of the default tracking domain, providing a more branded experience for your recipients. See [Custom Tracking Domains](/platform/emails/tracking/custom-domains) for setup instructions.
## Next Steps Learn how open tracking works and configure it for your routes Understand click tracking, link rewriting, and redirect behavior White-label tracking links with your own branded domain