Skip to main content

​
Overview

Open Tracking

1x1 invisible pixel tracks when emails are opened

Click Tracking

Links are rewritten to track clicks before redirecting

Analytics

View open/click rates in dashboard or via API

​
How It Works

When you send an email with tracking enabled:
  1. A transparent 1x1 pixel image is added to track opens
  2. All links in the email are rewritten through our tracking servers
  3. When the recipient opens the email or clicks a link, we record the event
  4. Events trigger webhooks and are available via the Events API

​
Open Tracking Pixel

GET/v1/track/open/:emailId
This endpoint serves a 1x1 transparent GIF pixel and records an open event for the email. It’s automatically embedded in emails when open tracking is enabled.

​
Behavior

  • Records the first open with timestamp in the opened_at field
  • Creates an email_event record with type opened
  • Captures user agent and IP address metadata
  • Triggers email.opened webhook if configured
  • Always returns a 1x1 transparent GIF with no-cache headers
Pixel URL
<img src="https://api.unosend.co/track/open/550e8400-e29b-41d4-a716-446655440000" 
     width="1" height="1" alt="" style="display:none" />

​
Response Headers

Content-Type: image/gif
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
Open tracking relies on image loading, which can be blocked by some email clients. Open rates should be considered a lower-bound estimate.

​
Click Tracking Redirect

GET/v1/track/click/:trackingId
This endpoint records a click event and redirects the user to the original URL. Links are automatically rewritten when click tracking is enabled.

​
Query Parameters

​
url
string
URL-encoded destination (for broadcast mode)
​
tid
string
Optional tracking identifier

​
Behavior

  • Looks up original URL from the tracking ID or uses the url query param
  • Creates an email_event record with type clicked
  • Captures user agent, IP address, and referer metadata
  • Triggers email.clicked webhook if configured
  • Returns 302 redirect to the original destination URL
Tracked Link Example
<!-- Original link -->
<a href="https://example.com/page">Click here</a>

<!-- Becomes -->
<a href="https://api.unosend.co/track/click/abc123?url=https%3A%2F%2Fexample.com%2Fpage">Click here</a>

​
Response

HTTP/1.1 302 Found
Location: https://example.com/page

​
Enable Tracking When Sending

To enable tracking, include the tracking options when sending an email: 
curl -X POST https://api.unosend.co/emails \
  -H "Authorization: Bearer un_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": "recipient@example.com",
    "subject": "Hello",
    "html": "<p>Check out <a href=\"https://example.com\">our site</a>!</p>",
    "tracking": {
      "open": true,
      "click": true
    }
  }'
You can enable open tracking and click tracking independently based on your needs.

​
Webhook Events

When opens or clicks are tracked, webhooks are triggered:

​
email.opened

email.opened webhook
{
  "type": "email.opened",
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "opened_at": "2024-01-15T10:45:00.000Z",
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.1"
  },
  "created_at": "2024-01-15T10:45:00.000Z"
}

​
email.clicked

email.clicked webhook
{
  "type": "email.clicked",
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://example.com/page",
    "clicked_at": "2024-01-15T10:47:00.000Z",
    "user_agent": "Mozilla/5.0...",
    "ip_address": "192.168.1.1"
  },
  "created_at": "2024-01-15T10:47:00.000Z"
}
IP addresses and user agents are collected for analytics. Make sure your privacy policy reflects this if you’re using tracking features.

​
Controlling Tracking

​
Via API

Use the tracking object to enable or disable open and click tracking per email: 
{
  "from": "hello@yourdomain.com",
  "to": ["user@example.com"],
  "subject": "Hello",
  "html": "<p>Check out <a href=\"https://example.com\">our site</a>!</p>",
  "tracking": {
    "open": true,
    "click": false
  }
}
OptionDefaultDescription
tracking.opentrueEnable open tracking (invisible pixel)
tracking.clicktrueEnable click tracking (link rewriting)

​
Via SMTP Headers

When using SMTP, add custom headers to control tracking: 
X-Unosend-Track-Opens: true
X-Unosend-Track-Clicks: false
Example with SMTP: 
From: hello@yourdomain.com
To: user@example.com
Subject: Hello
X-Unosend-Track-Opens: true
X-Unosend-Track-Clicks: false
Content-Type: text/html

<p>Hello!</p>
Set tracking.click to false if you don’t want links rewritten. This keeps original URLs intact, which can improve deliverability to some security-conscious recipients.

​
Broadcast Tracking

When sending broadcast (marketing) emails, tracking is automatically enabled by our infrastructure. No additional configuration is needed — the broadcast worker handles pixel injection and link rewriting for every recipient.

​
How Broadcast Tracking Works

  1. Open tracking pixel is injected before </body> in the HTML content
  2. All links in the HTML are rewritten to pass through our click tracking servers
  3. Each recipient gets a unique message_id with a bc- prefix (e.g., bc-a1b2c3d4-...@unosend.co)
  4. The bid (broadcast ID) query parameter links tracking events back to the broadcast

​
Broadcast Tracking URLs

Open pixel format: 
<img src="https://api.unosend.co/track/open/{message_id}?bid={broadcast_id}"
     width="1" height="1" alt="" style="display:none" />
Click tracking format: 
<!-- Original -->
<a href="https://example.com/page">Click here</a>

<!-- Rewritten -->
<a href="https://api.unosend.co/track/click/{message_id}?url=https%3A%2F%2Fexample.com%2Fpage&bid={broadcast_id}">Click here</a>
The following links are not rewritten for click tracking:
  • mailto: links
  • tel: links
  • Unsubscribe URLs ({{unsubscribe_url}})
  • Existing tracking pixel URLs

​
Broadcast Statistics

Open and click events update the opened_at and clicked_at timestamps on each recipient’s broadcast_emails record. The broadcast detail page calculates aggregate stats (open rate, click rate, bounce rate, unsubscribe rate) from these individual records.
Broadcast tracking is always enabled and cannot be disabled per-broadcast. Only the first open and first click per recipient are recorded.