Skip to main content
The OpenEvent interface represents a single email open event with detailed metadata including device information, geolocation, and duplicate/suppression status.

​
Fields

​
number
required
Auto-incrementing unique identifier for the open event. This is the primary key.
​
string
required
Identifier for the tracked email that was opened. References the email_id from TrackedEmail.
​
string
required
Identifier for the user or account that owns this tracking record. Used for data isolation.
​
string
required
Email address of the recipient who opened the email.
​
string
required
ISO 8601 timestamp indicating when the email was opened. Format: YYYY-MM-DDTHH:mm:ss.sssZ
​
string | null
IP address from which the email was opened. May be null if the IP address could not be determined. IPv6-mapped IPv4 addresses are normalized to standard IPv4 format.
​
string | null
User agent string from the HTTP request. May be null if not provided. Used for device type detection and duplicate detection.
​
string | null
Country name derived from IP geolocation. May be null if geolocation lookup failed or IP address was not available.
​
string | null
Region or state name derived from IP geolocation. May be null if not available.
​
string | null
City name derived from IP geolocation. May be null if not available.
​
number | null
Latitude coordinate from IP geolocation. May be null if not available.
​
number | null
Longitude coordinate from IP geolocation. May be null if not available.
​
'phone' | 'computer' | 'other'
required
Type of device used to open the email, detected from the user agent string:
  • phone - Mobile devices and tablets
  • computer - Desktop computers and laptops
  • other - Unknown or unrecognized devices
​
number
required
Flag indicating whether this open was classified as a duplicate:
  • 0 - Unique open event
  • 1 - Duplicate open (same email opened multiple times from same IP/user agent within a time window)
Duplicate opens are excluded from the open_count metric.
​
number
required
Flag indicating whether this open was suppressed by the sender:
  • 0 - Normal open event
  • 1 - Suppressed open (sender called mark-suppress-next before the open occurred)
Suppressed opens are typically from email client prefetching and are excluded from the open_count metric.
​
string | null
Reason for suppression if is_sender_suppressed is 1. Currently, the only value is:
  • "mark_suppress_next" - Suppressed via the mark-suppress-next endpoint
  • null - Not suppressed

​
Returned by

  • GET /dashboard/api/open-events - Returns an array of OpenEvent objects
    • Without query params: Returns all non-duplicate, non-suppressed open events
    • With email_id query param: Returns open events for a specific email

​
Database schema

Stored in the open_events table with the following SQLite schema:

​
Example response