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
`metadata`	object?	Event details (see below)

Metadata

Field	Type	Present on
`reason`	string	Bounce, rejection, drop, complaint
`smtp_code`	integer	bounced, rejected, deferred
`smtp_message`	string	bounced, rejected, deferred
`user_agent`	string	opened, clicked
`url`	string	clicked
`ip`	string	opened, clicked

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, will be retried (greylisting, server busy, IP temporarily blocked, connection issues)

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"
  }
}

soft_bounced Soft bounce (mailbox full, inactive recipient)

Metadata: reason, smtp_code, smtp_message

reason	meaning
`recipient_over_quota`	Recipient mailbox is full
`recipient_soft_bounced`	Temporary recipient-side failure, address still valid
`recipient_inactive`	Recipient mailbox is inactive

{
  "event_id": "01990a3b-1a03-7c11-9e00-4a1b2c3d0003",
  "recipient": "user@example.com",
  "event_type": "soft_bounced",
  "event_time": "2026-03-24T10:45:31Z",
  "custom_id": "order-1234",
  "metadata": {
    "reason": "recipient_over_quota",
    "smtp_code": 452,
    "smtp_message": "4.2.2 Mailbox full"
  }
}

hard_bounced Permanent bounce: the recipient address is invalid, or the receiving server is unreachable

Metadata: reason, smtp_code, smtp_message

reason	meaning
`recipient_unknown`	Recipient address does not exist
`no_mx_records`	Recipient domain has no mail server
`connection_issue`	Recipient server could not be reached at all

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

dropped Did not leave our platform: gated before sending, or delivery gave up (internal/infrastructure)

Metadata: reason

reason	meaning
`domain_invalid`	Recipient domain is not a valid mail domain
`domain_typo`	Recipient domain looks like a typo (e.g. gmial.com)
`domain_disposable`	Recipient uses a disposable email domain
`recipient_is_blocked`	Recipient was blocked after repeated failures
`recipient_is_opted_out`	Recipient unsubscribed from your mail
`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_allowed`	Sending from this domain is not allowed
`abandoned`	Gave up after exhausting delivery retries

{
  "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",
  "metadata": {
    "reason": "domain_typo"
  }
}

rejected Remote server refused the message or sender (spam, policy, relay)

Metadata: reason, smtp_code, smtp_message

reason	meaning
`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

{
  "event_id": "01990a3b-1a09-7c11-9e00-4a1b2c3d0009",
  "recipient": "user@example.com",
  "event_type": "rejected",
  "event_time": "2026-03-24T10:45:29Z",
  "custom_id": "receipt-8842",
  "metadata": {
    "reason": "spam_detected",
    "smtp_code": 550,
    "smtp_message": "5.7.1 Message rejected due to content restrictions"
  }
}

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"
}

spam_reported Recipient marked your email as spam (feedback-loop complaint)

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"
}

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.

For webhook signature verification, see Webhook Security.