email.onOpened

A tracked message was opened — with client details and a bot verdict.

Fires when a tracked message is opened. Client, device, and location details come along when the provider reports them — plus emailkit’s botDetection verdict, so security scanners don’t inflate your numbers.

hooks: {
  email: {
    onOpened: async (event) => {
      if (event.botDetection?.isBot) return; // e.g. reason: "known-bot-agent"
      await markOpened(event.messageId);
    },
  },
},

How the classifier decides — and the exported checkOpenBot helper — is covered in Bots don’t count.

Payload

PropType

emailDriver?string

EmailKit driver id that produced this event, attached by the EmailKit client.

Typestring

schemaVersion?"1"

Schema version for forward-compat

Type"1"

eventId?string

Unique event identifier for dedupe

Typestring

messageIdstring

Unique message identifier from the email provider

Typestring

providerId?string

Provider-specific message identifier (in addition to messageId). This is the provider's internal ID for this message, separate from the RFC Message-ID. Useful for provider-specific operations or tracking.

Typestring

recipientstring

Email address of the recipient (always available)

Typestring

status

| "sent"
    | "delivered"
    | "opened"
    | "clicked"
    | "bounced"
    | "complained"
    | "rejected"

Event status/type

Type

| "sent"
    | "delivered"
    | "opened"
    | "clicked"
    | "bounced"
    | "complained"
    | "rejected"

timestampDate

Timestamp when the event occurred

TypeDate

from?EmailAddress

Sender email address (available in sent/accepted events)

TypeEmailAddress

to?EmailAddress[]

Recipient email addresses (available in sent/accepted events)

TypeEmailAddress[]

subject?string

Email subject (available in sent/accepted events)

Typestring

tags?EmailTag[]

Custom metadata/tags associated with the email

TypeEmailTag[]

metadata?Record<string, string>

Custom metadata key-value pairs

TypeRecord<string, string>

campaignId?string

Campaign or tracking identifier

Typestring

recipientDomain?string

Domain of the recipient (e.g., "gmail.com")

Typestring

server?string

Receiving server information

Typestring

raw?unknown

Provider-specific raw data (for debugging or advanced use cases)

Typeunknown

ip?string

IP address of the user who opened/clicked

Typestring

userAgent?string

User agent string of the browser/client

Typestring

location?

{
    /** City name */
    city?: string;
    /** Country code or name */
    country?: string;
    /** Region/state */
    region?: string;
    /** Timezone */
    timezone?: string;
  }

Geolocation information

Type

{
    /** City name */
    city?: string;
    /** Country code or name */
    country?: string;
    /** Region/state */
    region?: string;
    /** Timezone */
    timezone?: string;
  }

deviceType?string

Device type (mobile, desktop, tablet, etc.)

Typestring

clientType?string

Email client name (Gmail, Outlook, etc.)

Typestring

os?string

Operating system

Typestring

botDetection?

{
    /** Whether this is detected as a bot */
    isBot: boolean;
    /** Reason for the bot detection decision */
    reason: string;
  }

Bot detection result

Type

{
    /** Whether this is detected as a bot */
    isBot: boolean;
    /** Reason for the bot detection decision */
    reason: string;
  }

timeSinceSendMs?number

Milliseconds since send (or delivery), if available

Typenumber