Message types

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

string

required

Must be "tracker:getComposeTrackingData"

string

Email address(es) of the recipient(s). Defaults to "unknown" if not provided.

string

Email address of the sender. Optional and defaults to empty string if not provided.

Response

boolean

Indicates if the request was successful

string

Unique identifier for the user

string

Generated UUID for this email

string

ISO 8601 timestamp of when the tracking data was generated

string

Recipient email address (trimmed)

string | null

Sender email address (trimmed and lowercased) or null

string

Encoded tracking token containing the tracking payload

string

Complete URL to the tracking pixel image

string

Base URL of the tracker server

Example

const response = await chrome.runtime.sendMessage({
  type: "tracker:getComposeTrackingData",
  recipient: "user@example.com",
  senderEmail: "sender@example.com"
});

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

string

required

Must be "tracker:logTrackedEmail"

object

required

Email tracking data to log

string

required

UUID of the tracked email

string

Recipient email address. Defaults to "unknown"

string

Sender email address. Defaults to empty string

string

Email subject line. Defaults to empty string

string

required

ISO 8601 timestamp of when the email was sent

string

required

URL to the tracking pixel

Response

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

string

required

Must be "tracker:getInboxBadgeData"

Response

boolean

Indicates if the request was successful

string

Base URL of the tracker server

array

Array of enriched email tracking data

string

UUID of the tracked email

string

Recipient email address

string

Sender email address

string

Email subject line

string

ISO 8601 timestamp of when the email was sent

string

URL to the tracking pixel

number

Total number of open events for this email

number

Number of unique opens (deduplicated)

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

string

required

Must be "tracker:getPopupData"

Response

boolean

Indicates if the request was successful

string

Unique identifier for the user

string

Base URL of the tracker server

string

Dashboard authentication token

array

Array of recent tracked emails from local storage

array

Recent emails enriched with server-side tracking data

array

Debug information for troubleshooting

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

string

required

Must be "tracker:updateTrackerBaseUrl"

string

required

New tracker base URL (e.g., "http://localhost:8090" or "https://tracker.example.com")

Response

boolean

Indicates if the request was successful

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

string

required

Must be "tracker:updateDashboardToken"

string

required

Dashboard authentication token

Response

boolean

Indicates if the request was successful

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

string

required

Must be "tracker:markSuppressNext"

string

required

UUID of the email to mark for suppression

Response

boolean

Indicates if the request was successful

boolean

Whether the suppression request was successfully sent to the server

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;
});

Server API

Extension API

Data Models

tracker:getComposeTrackingData

Request

Response

Example

tracker:logTrackedEmail

Request

Response

Example

tracker:getInboxBadgeData

Request

Response

Example

tracker:getPopupData

Request

Response

Example

tracker:updateTrackerBaseUrl

Request

Response

Example

tracker:updateDashboardToken

Request

Response

Example

tracker:markSuppressNext

Request

Response

Example

Implementation details

​tracker:getComposeTrackingData

​Request

​Response

​Example

​tracker:logTrackedEmail

​Request

​Response

​Example

​tracker:getInboxBadgeData

​Request

​Response

​Example

​tracker:getPopupData

​Request

​Response

​Example

​tracker:updateTrackerBaseUrl

​Request

​Response

​Example

​tracker:updateDashboardToken

​Request

​Response

​Example

​tracker:markSuppressNext

​Request

​Response

​Example

​Implementation details

tracker:getComposeTrackingData

Request

Response

Example

tracker:logTrackedEmail

Request

Response

Example

tracker:getInboxBadgeData

Request

Response

Example

tracker:getPopupData

Request

Response

Example

tracker:updateTrackerBaseUrl

Request

Response

Example

tracker:updateDashboardToken

Request

Response

Example

tracker:markSuppressNext

Request

Response

Example

Implementation details