Skip to main content
The TrackedEmail interface represents a tracked email record with aggregated open count statistics. This is the primary model for email tracking data stored in the database.

​
Fields

​
email_id
string
required
Unique identifier for the tracked email. This is the primary key and matches the email_id from the TrackingPayload.
​
user_id
string
required
Unique identifier for the user or account that owns this tracked email. Used for data isolation and multi-tenant filtering.
​
recipient
string
required
Email address of the recipient who received this email.
​
sender_email
string | null
Email address of the sender. This field may be null if not provided when creating the tracking record.
​
sent_at
string
required
ISO 8601 timestamp indicating when the email was sent. Format: YYYY-MM-DDTHH:mm:ss.sssZ
​
open_count
number
required
Number of unique, counted opens for this email. This count excludes:
  • Duplicate opens (detected by IP address, user agent, and timing)
  • Sender-suppressed opens (opens prevented by mark-suppress-next)
This is the primary metric for tracking genuine recipient engagement.
​
created_at
string
required
ISO 8601 timestamp indicating when this tracking record was created in the database. Automatically set to the current time when the record is inserted.

​
Returned by

  • GET /dashboard/api/emails - Returns an array of TrackedEmail objects with additional computed fields:
    • unique_open_count - Same as open_count
    • total_open_events - Total counted opens (non-duplicate, non-suppressed)
    • raw_open_events - Total raw opens including duplicates and suppressed
    • last_opened_at - Timestamp of the most recent counted open
    • opened - Boolean indicating if the email has been opened

​
Database schema

Stored in the tracked_emails table with the following SQLite schema: 
CREATE TABLE tracked_emails (
  email_id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  recipient TEXT NOT NULL,
  sender_email TEXT,
  sent_at TEXT NOT NULL,
  open_count INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

​
Example response

{
  "email_id": "email_456",
  "user_id": "user_123",
  "recipient": "[email protected]",
  "sender_email": "[email protected]",
  "sent_at": "2024-01-15T10:30:00.000Z",
  "open_count": 3,
  "created_at": "2024-01-15T10:30:00.000Z"
}
  • TrackingPayload - Input data used to create tracked emails
  • OpenEvent - Individual open events associated with tracked emails

Build docs developers (and LLMs) love

Get started for freeTalk to us