Skip to main content
The Email Tracker extension uses Chrome’s message passing API to communicate between content scripts and the service worker. All messages follow a request/response pattern using chrome.runtime.sendMessage.

​
tracker:getComposeTrackingData

Generates tracking data for a new email being composed. This message is sent when a user is about to send an email in Gmail.

​
Request

​
type
string
required
Must be "tracker:getComposeTrackingData"
​
recipient
string
Email address(es) of the recipient(s). Defaults to "unknown" if not provided.
​
senderEmail
string
Email address of the sender. Optional and defaults to empty string if not provided.

​
Response

​
ok
boolean
Indicates if the request was successful
​
userId
string
Unique identifier for the user
​
emailId
string
Generated UUID for this email
​
sentAt
string
ISO 8601 timestamp of when the tracking data was generated
​
recipient
string
Recipient email address (trimmed)
​
senderEmail
string | null
Sender email address (trimmed and lowercased) or null
​
token
string
Encoded tracking token containing the tracking payload
​
pixelUrl
string
Complete URL to the tracking pixel image
​
baseUrl
string
Base URL of the tracker server

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:getComposeTrackingData",
  recipient: "[email protected]",
  senderEmail: "[email protected]"
});

if (response?.ok) {
  const img = document.createElement("img");
  img.src = response.pixelUrl;
  img.width = 1;
  img.height = 1;
  // Append to email body
}

​
tracker:logTrackedEmail

Logs a tracked email to local storage for display in the popup and inbox badges.

​
Request

​
type
string
required
Must be "tracker:logTrackedEmail"
​
payload
object
required
Email tracking data to log
​
payload.emailId
string
required
UUID of the tracked email
​
payload.recipient
string
Recipient email address. Defaults to "unknown"
​
payload.senderEmail
string
Sender email address. Defaults to empty string
​
payload.subject
string
Email subject line. Defaults to empty string
​
payload.sentAt
string
required
ISO 8601 timestamp of when the email was sent
​
payload.pixelUrl
string
required
URL to the tracking pixel

​
Response

​
ok
boolean
Indicates if the request was successful

​
Example

chrome.runtime.sendMessage({
  type: "tracker:logTrackedEmail",
  payload: {
    emailId: response.emailId,
    recipient: response.recipient,
    senderEmail: response.senderEmail || "",
    subject: "Meeting Tomorrow",
    sentAt: response.sentAt,
    pixelUrl: response.pixelUrl
  }
});

​
tracker:getInboxBadgeData

Retrieves enriched tracking data for recent emails to display badges in the Gmail inbox.

​
Request

​
type
string
required
Must be "tracker:getInboxBadgeData"

​
Response

​
ok
boolean
Indicates if the request was successful
​
trackerBaseUrl
string
Base URL of the tracker server
​
items
array
Array of enriched email tracking data
​
items[].emailId
string
UUID of the tracked email
​
items[].recipient
string
Recipient email address
​
items[].senderEmail
string
Sender email address
​
items[].subject
string
Email subject line
​
items[].sentAt
string
ISO 8601 timestamp of when the email was sent
​
items[].pixelUrl
string
URL to the tracking pixel
​
items[].totalOpenEvents
number
Total number of open events for this email
​
items[].uniqueOpenCount
number
Number of unique opens (deduplicated)
​
items[].lastOpenedAt
string | null
ISO 8601 timestamp of the last open event, or null if never opened

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:getInboxBadgeData"
});

if (response?.ok && Array.isArray(response.items)) {
  response.items.forEach(item => {
    console.log(`Email ${item.emailId}: ${item.totalOpenEvents} opens`);
  });
}

​
tracker:getPopupData

Retrieves comprehensive data for the extension popup UI, including recent emails, enriched tracking data, and debug information.

​
Request

​
type
string
required
Must be "tracker:getPopupData"

​
Response

​
ok
boolean
Indicates if the request was successful
​
userId
string
Unique identifier for the user
​
trackerBaseUrl
string
Base URL of the tracker server
​
dashboardToken
string
Dashboard authentication token
​
recentEmails
array
Array of recent tracked emails from local storage
​
enrichedRecentEmails
array
Recent emails enriched with server-side tracking data
​
debugItems
array
Debug information for troubleshooting
​
debugGeneratedAt
string
ISO 8601 timestamp when the debug data was generated

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:getPopupData"
});

if (response?.ok) {
  console.log(`User ID: ${response.userId}`);
  console.log(`Recent emails: ${response.enrichedRecentEmails.length}`);
}

​
tracker:updateTrackerBaseUrl

Updates the tracker server base URL in extension storage.

​
Request

​
type
string
required
Must be "tracker:updateTrackerBaseUrl"
​
baseUrl
string
required
New tracker base URL (e.g., "http://localhost:8090" or "https://tracker.example.com")

​
Response

​
ok
boolean
Indicates if the request was successful
​
trackerBaseUrl
string
The normalized base URL that was saved

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:updateTrackerBaseUrl",
  baseUrl: "https://tracker.example.com"
});

if (response?.ok) {
  console.log(`Base URL updated to: ${response.trackerBaseUrl}`);
}

​
tracker:updateDashboardToken

Updates the dashboard authentication token in extension storage.

​
Request

​
type
string
required
Must be "tracker:updateDashboardToken"
​
dashboardToken
string
required
Dashboard authentication token

​
Response

​
ok
boolean
Indicates if the request was successful
​
dashboardToken
string
The token that was saved

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:updateDashboardToken",
  dashboardToken: "your-secret-token"
});

if (response?.ok) {
  console.log("Dashboard token updated successfully");
}

​
tracker:markSuppressNext

Marks an email to suppress the next open event. This is used when the sender views their own sent email to avoid tracking themselves.

​
Request

​
type
string
required
Must be "tracker:markSuppressNext"
​
emailId
string
required
UUID of the email to mark for suppression

​
Response

​
ok
boolean
Indicates if the request was successful
​
sent
boolean
Whether the suppression request was successfully sent to the server
​
reason
string
Status message: "ok" on success, error description on failure

​
Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:markSuppressNext",
  emailId: "550e8400-e29b-41d4-a716-446655440000"
});

if (response?.ok && response.sent) {
  console.log("Suppression marked successfully");
}

​
Implementation details

All message handlers are implemented in serviceWorker.js:19-116. The service worker uses an async IIFE pattern with sendResponse and returns true to indicate asynchronous response handling: 
chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
  (async () => {
    if (message?.type === "tracker:getComposeTrackingData") {
      const userId = await ensureUserId();
      const emailId = crypto.randomUUID();
      const sentAt = new Date().toISOString();
      const recipient = (message.recipient || "unknown").trim();
      const senderEmail = String(message.senderEmail || "").trim().toLowerCase() || null;
      const baseUrl = await getTrackerBaseUrl();
      const token = encodeTrackingToken({
        user_id: userId,
        email_id: emailId,
        recipient,
        sender_email: senderEmail ?? undefined,
        sent_at: sentAt
      });
      const pixelUrl = `${baseUrl}/t/${token}.gif`;

      sendResponse({ ok: true, userId, emailId, sentAt, recipient, senderEmail, token, pixelUrl, baseUrl });
      return;
    }
    // ... other handlers
  })().catch((error) => {
    sendResponse({ ok: false, error: String(error?.message || error) });
  });

  return true;
});

Build docs developers (and LLMs) love

Get started for freeTalk to us