Email Events

Events track each email from submission to engagement. Delivered via webhooks or Pub/Sub in real time.

Setup

To receive events, configure an event subscriber in the portal under the Event Subscribers section of the organization you want to track. Each organization can have its own subscribers with independent endpoints and credentials.

You can also configure a default event subscriber at the account level (in Account Settings). New organizations created under that account will automatically inherit the default subscriber configuration.

Envelope

{
  "topic": "email.events",
  "eventTime": "2026-03-24T10:45:30Z",
  "payload": {
    "event_id": "9b1c3f2a-7e4d-4a11-8c2b-2a6f5e1d0c33",
    "recipient": "user@example.com",
    "event_type": "delivered",
    "event_time": "2026-03-24T10:45:30Z",
    "custom_id": "order-1234"
  }
}

Payload Fields

Field	Type	Description
`event_id`	string (UUID)	Unique event id. Use it to dedup webhook retries and reconcile events
`recipient`	string	Recipient email address
`event_type`	string	Event type (see below)
`event_time`	ISO 8601	When the event occurred
`custom_id`	string?	Your identifier, passed at send time
`recipient_status`	string?	What the event means for the address itself (see below)
`metadata`	object?	Event details (see below)

Metadata

Field	Type	Present on
`reason`	string	rejected, dropped, deferred
`smtp_code`	integer	rejected, deferred, dropped
`smtp_message`	string	rejected, deferred, dropped
`user_agent`	string	opened, clicked
`url`	string	clicked
`ip`	string	opened, clicked

Recipient status

When recipient_status is present, the event says something about the address itself and you probably need to act on your list.

Value	What it means	What to do
`undeliverable`	The address is dead, or has failed often enough that we have stopped sending to it	Remove it from your list
`at_risk`	Delivery failed for a reason that usually clears, such as a full or inactive mailbox	Back off, keep the address
`complained`	The recipient reported your mail as spam	Remove it and never re-add it
`unsubscribed`	The recipient opted out of your mail	Remove it, unless they opt in again

Event Types

Click an event type to see its description, metadata fields, and JSON example.

delivered Accepted by the recipient's mail server

Metadata: None

No reason.

{
  "event_id": "01990a3b-1a01-7c11-9e00-4a1b2c3d0001",
  "recipient": "user@example.com",
  "event_type": "delivered",
  "event_time": "2026-03-24T10:45:30Z",
  "custom_id": "order-1234"
}

deferred Temporary issue, it will be retried

Metadata: reason, smtp_code, smtp_message

reason	meaning
`greylisted`	Recipient server asked us to try again shortly
`server_busy`	Recipient server was temporarily overloaded
`ip_blocked`	Sending IP was temporarily blocked by the recipient
`connection_issue`	Could not reach the recipient server (timeout, reset, refused)

{
  "event_id": "01990a3b-1a02-7c11-9e00-4a1b2c3d0002",
  "recipient": "user@example.com",
  "event_type": "deferred",
  "event_time": "2026-03-24T10:45:30Z",
  "custom_id": "order-1234",
  "metadata": {
    "reason": "greylisted",
    "smtp_code": 421,
    "smtp_message": "4.7.0 Try again later"
  }
}

dropped Stopped before delivery

Metadata: reason, smtp_code, smtp_message

reason	meaning
`domain_invalid`	Recipient domain is not a valid mail domain
`domain_no_mx`	Recipient domain has no MX record, so it cannot receive mail
`domain_typo`	Recipient domain looks like a typo (e.g. gmial.com)
`domain_disposable`	Recipient uses a disposable email domain
`recipient_blocked_permanently`	Recipient is suppressed: a hard bounce, or repeated failures with no recovery left
`recipient_blocked_temporarily`	Recipient is in a cooldown after recent failures and will be retried later
`recipient_unsubscribed`	Recipient unsubscribed from your mail
`recipient_complained`	Recipient previously reported your mail as spam, so nothing more is sent to them
`tenant_domain_spf_not_verified`	Your sending domain has no verified SPF
`tenant_domain_dkim_not_verified`	Your sending domain has no verified DKIM
`tenant_domain_not_found`	This sending domain is not registered for your organization
`abandoned`	Gave up after exhausting delivery retries
`virus_detected`	An attachment contained malware and was blocked before sending
`attachment_too_large`	An attachment is too large to be processed, so the email cannot be sent

{
  "event_id": "01990a3b-1a05-7c11-9e00-4a1b2c3d0005",
  "recipient": "user@gmial.com",
  "event_type": "dropped",
  "event_time": "2026-03-24T10:45:29Z",
  "custom_id": "reset-pwd-99",
  "recipient_status": "undeliverable",
  "metadata": {
    "reason": "domain_typo"
  }
}

rejected The recipient server refused the message

Metadata: reason, smtp_code, smtp_message

reason	meaning
`recipient_unknown`	Recipient address does not exist
`recipient_mailbox_full`	Recipient mailbox is full
`recipient_inactive`	Recipient mailbox is inactive
`recipient_temporary_failure`	Temporary recipient-side failure, address still valid
`spam_detected`	Recipient server rejected the message as spam
`policy_violation`	Recipient server rejected it for a policy reason
`relay_access_denied`	Recipient server refused to relay the message
`virus_detected`	Recipient server rejected the message for malware in an attachment

{
  "event_id": "01990a3b-1a09-7c11-9e00-4a1b2c3d0009",
  "recipient": "unknown@example.com",
  "event_type": "rejected",
  "event_time": "2026-03-24T10:45:31Z",
  "custom_id": "welcome-42",
  "recipient_status": "undeliverable",
  "metadata": {
    "reason": "recipient_unknown",
    "smtp_code": 550,
    "smtp_message": "5.1.1 User unknown"
  }
}

opened Recipient opened the email

Metadata: user_agent, ip

No reason.

{
  "event_id": "01990a3b-1a06-7c11-9e00-4a1b2c3d0006",
  "recipient": "user@example.com",
  "event_type": "opened",
  "event_time": "2026-03-24T11:00:05Z",
  "custom_id": "order-1234",
  "metadata": {
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "ip": "203.0.113.42"
  }
}

clicked Recipient clicked a link

Metadata: url, user_agent, ip

No reason.

{
  "event_id": "01990a3b-1a07-7c11-9e00-4a1b2c3d0007",
  "recipient": "user@example.com",
  "event_type": "clicked",
  "event_time": "2026-03-24T11:02:15Z",
  "custom_id": "order-1234",
  "metadata": {
    "url": "https://yourdomain.com/orders/1234",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
    "ip": "203.0.113.42"
  }
}

unsubscribed One-click unsubscribe

Metadata: None

No reason.

{
  "event_id": "01990a3b-1a08-7c11-9e00-4a1b2c3d0008",
  "recipient": "user@example.com",
  "event_type": "unsubscribed",
  "event_time": "2026-03-24T11:05:00Z",
  "custom_id": "order-1234",
  "recipient_status": "unsubscribed"
}

spam_reported Recipient marked your email as spam

Metadata: None

No reason.

{
  "event_id": "01990a3b-1a0a-7c11-9e00-4a1b2c3d000a",
  "recipient": "user@example.com",
  "event_type": "spam_reported",
  "event_time": "2026-03-24T12:30:00Z",
  "custom_id": "order-1234",
  "recipient_status": "complained"
}

Engagement tracking (opened, clicked)

Open and click tracking must be enabled in the portal (organization settings) to receive opened and clicked events. When enabled, email links are rewritten to pass through the Mailverick redirection server (https://links.mailverick.com). To show your own domain instead (e.g. links.yourdomain.com), configure a tracking CNAME record for your sending domain in the portal's domain section.

About virus_detected: take this reason very seriously. It means malware was found in an attachment. On a dropped event our own scanner caught it before the email left our platform; on a rejected event the recipient's mail server refused it. Investigate immediately: the system or integration producing these emails may be compromised. Repeated detections trigger abuse enforcement and can lead to the suspension of your organization or account.

For webhook signature verification, see Webhook Security.