Copy page

Tracking

Click Tracking

How It Works

When click tracking is enabled for a route, Lettermint automatically rewrites links in your HTML emails to route through our tracking domain. The original link:

Code
<a href="https://example.com/product/123">View Product</a>

Becomes:

Code
<a href="https://p{sid}.t.ltrmnt.com/c/{tracking_token}">View Product</a>

Where {sid} is your project's short ID.

Redirect Flow

When a recipient clicks a tracked link:

1. Click observed — Request hits the tracking domain and we store the click observation with timestamp
2. Token validated - We verify the tracking token is valid and not expired
3. Instant redirect - Recipient is immediately redirected (302) to the original URL
4. Classification and promotion - The observation is classified before it contributes to customer-visible events and metrics
5. Webhook sent - Human-countable clicks send a message.clicked event to your configured webhooks

The redirect happens in milliseconds, providing a seamless experience for recipients.

Enabling Click 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 Clicks
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_clicks": true}'

Per-Email Override

You can override the route's click tracking setting for a single email. This lets you keep a route default while opting individual messages in or out.

API sends use settings.track_clicks:

Code
{
  "from": "sender@yourdomain.com",
  "to": ["recipient@example.com"],
  "subject": "Your download link",
  "html": "<p><a href=\"https://example.com/download\">Download</a></p>",
  "settings": {
    "track_clicks": false
  }
}

SMTP sends use the Lettermint override header:

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

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

Which Links Are Tracked

Tracked Links

Lettermint rewrites standard HTTP/HTTPS links:

• https://example.com/page
• http://example.com/page
• Links in <a href="..."> tags
• Links in HTML email content

Skipped Links

The following link types are not rewritten to preserve functionality:

Link Type	Example	Reason
Email links	mailto:support@example.com	Opens email client
Phone links	tel:+1234567890	Opens phone dialer
SMS links	sms:+1234567890	Opens messaging app
JavaScript	javascript:void(0)	Client-side only
Anchors	#section-name	Same-page navigation
Data URIs	data:image/png;base64,...	Embedded content
Unsubscribe links	Links with unsubscribe in URL	Preserve direct access

Bot Detection

Security scanners and link preview features can click links before humans do. Lettermint detects these automated clicks to ensure accurate analytics.

Webhook Payload

When a human-countable click is detected, Lettermint sends a message.clicked webhook event. Machine, link preview, and security scanner clicks are excluded by default and are only sent to webhooks with Include machine events enabled.

Code
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567892",
  "event": "message.clicked",
  "timestamp": "2025-08-08T20:18:30.000Z",
  "data": {
    "message_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "subject": "Your weekly recommendations",
    "metadata": {
      "X-Campaign-ID": "weekly-recs"
    },
    "tag": "recommendations",
    "recipient": "user@example.com",
    "clicked_at": "2025-08-08T20:18:30+00:00",
    "destination_url": "https://example.com/product/123",
    "link_index": 0,
    "anchor_text": "View Product",
    "first_click": true,
    "device_type": "mobile",
    "client_type": "browser",
    "client_name": "Safari",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)...",
    "bot": {
      "detected": false,
      "probability": 0,
      "classification": "genuine",
      "proxy_type": null,
      "reason_codes": [],
      "machine": false,
      "counts_for_metrics": true
    }
  }
}

Click-specific fields:

• destination_url - The original destination URL that was clicked
• link_index - Zero-based index of the link in the email (order of appearance)
• anchor_text - The visible text of the clicked link
• clicked_at - Timestamp when the click occurred

Engagement fields:

• first_click - true if this is the first time this recipient clicked any link in this 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 click 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 click is classified as machine, preview, or security activity
• bot.counts_for_metrics - Whether the click contributes to default engagement metrics

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

Limitations

Token Expiration

Tracking tokens expire 30 days after the email is sent. After expiration:

• Clicks are not recorded
• Recipients are still redirected to the original URL (graceful degradation)

Corporate Security Pre-clicking

Some corporate email security tools pre-click all links in emails to scan for malware. Lettermint excludes identified security scanner clicks from default metrics and webhooks. They remain available to opted-in webhooks and reporting requests that include machine activity.

Plain Text Emails

Click tracking only works for HTML emails. Links in plain-text email parts are not rewritten.

Link Appearance

The tracking URL is visible if recipients hover over links or inspect the email source. This is standard for email tracking and does not affect the user experience. For a more branded appearance, consider using a custom tracking domain.

Best Practices

1. Track specific campaigns - Use metadata and tags to attribute clicks to campaigns
2. Monitor unique clicks - Use first_click to distinguish initial engagement from repeat clicks
3. Test your links - Send test emails to verify tracked links redirect correctly
4. Respect privacy - Disclose tracking in your privacy policy

Next Steps

• Open Tracking - Combine with open tracking for complete engagement data
• Webhook Events - Full payload reference for all tracking events
• Tags - Organize and filter your tracked emails