Events

Read the event log — every delivery and engagement event that fired for your workspace (delivered, opened, clicked, bounced, complained, failed), newest first. This is a pull log: events are recorded for every email whether or not you've configured a webhook endpoint, so you can poll this endpoint to observe what happened to your sends without setting up any webhooks. Each event also carries a per-endpoint delivery summary if you do have webhook endpoints. Read-only — to configure endpoints and verify signatures, see Webhooks.

Overview

Method	Path	Description
`GET`	`/api/v1/events`	List webhook events (cursor-paginated)

The event object

Each event in the list has this shape:

Field	Type	Description
`id`	`string`	The event ID, prefixed evt_ (e.g. evt_3f1a8c2e-…).
`type`	`string`	The event type, e.g. email.delivered.
`created_at`	`string`	ISO 8601 timestamp the event was recorded.
`deliveries`	`object[]`	Per-endpoint delivery summary for this event (see below).

The delivery object

Each entry in deliveries summarises delivery to one endpoint:

Field	Type	Description
`endpoint_id`	`string`	UUID of the webhook endpoint the event was delivered to.
`status`	`string`	Delivery status to that endpoint, e.g. succeeded, failed, or pending.
`attempts`	`number`	Number of delivery attempts made.
`last_status_code`	`number \| null`	HTTP status code from the most recent attempt, or null if not yet attempted.

The full email object is not duplicated here — fetch it from GET /api/v1/emails/{id} (see Emails).

List events

GET/api/v1/events

Returns a cursor-paginated list of webhook events, newest first. Pass next_cursor back as the cursor parameter to fetch the next page.

Query parameters

Field	Type	Required	Description
`limit`	`number`	optional	Max events to return. Default 50, max 100 (over-large values are clamped).
`cursor`	`string`	optional	Opaque pagination cursor from a previous response's next_cursor. Omit for the first page; a malformed cursor returns 400 invalid_field.
`type`	`string`	optional	Filter by event type. One of the six supported types listed below.

Filterable event types

The type parameter accepts exactly these six values; any other value returns 400 invalid_field:

Event type
`email.delivered`
`email.bounced`
`email.complained`
`email.failed`
`email.opened`
`email.clicked`

Response

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

// The returned page auto-paginates — iterate across every page transparently.
for "color:#ff7b72">await ("color:#ff7b72">const event of "color:#ff7b72">await ps.events.list({ limit: 100, "color:#ff7b72">type: "email.delivered" })) {
  console.log(event.id, event."color:#ff7b72">type, event.deliveries[0]?.status)
}

Errors

Errors use the standard envelope — unauthorized (401) and invalid_field (400, for an unsupported type or a malformed cursor). See the full Error codes reference for the canonical envelope.