Emails

Read back the emails your workspace has sent and their delivery status. These endpoints are read-only — to send, use Send email or Batch send.

Overview

Method	Path	Description
`GET`	`/api/v1/emails`	List sent emails (cursor-paginated)
`GET`	`/api/v1/emails/:id`	Get a single email by UUID

The email object

Both endpoints return the same object shape:

Field	Type	Description
`id`	`string`	The email's UUID — the same id POST /api/v1/send returns.
`to`	`string`	Recipient email address.
`subject`	`string`	Subject line.
`status`	`string`	Delivery status: sent, delivered, opened, clicked, failed, complained, bounced, or suppressed (a send blocked by the suppression list).
`type`	`string`	Send type: campaign, automation, or transactional.
`environment`	`string`	Which key sent it: live (delivered) or test (captured in the sandbox). See Test mode.
`sent_at`	`string`	ISO 8601 timestamp the email was sent.
`delivered_at`	`string \| null`	When the receiving server confirmed delivery, or null.
`opened_at`	`string \| null`	When the recipient first opened the email, or null.
`clicked_at`	`string \| null`	When the recipient first clicked a tracked link, or null.
`bounced_at`	`string \| null`	When the email bounced, or null.
`complained_at`	`string \| null`	When the recipient marked the email as spam (a complaint), or null.
`error`	`string \| null`	The failure reason — present only when status is "failed", otherwise null.

List emails

GET/api/v1/emails

Returns a cursor-paginated list of sent emails, newest first. Pass next_cursor from the response back as the cursor parameter to fetch the next page.

Query parameters

Field	Type	Required	Description
`limit`	`number`	optional	Max emails 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.
`status`	`string`	optional	Filter by delivery status. One of: sent, delivered, opened, clicked, bounced, complained, failed, suppressed.
`type`	`string`	optional	Filter by send type. One of: campaign, automation, transactional.
`environment`	`string`	optional	Filter by send environment. One of: live, test (test-mode captured sends).

Note: The selectable status filters are every status an email can hold — sent, delivered, opened, clicked, bounced, complained, failed, and suppressed (a send blocked by the suppression list). Any other value returns 400 invalid_field.

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 email of "color:#ff7b72">await ps.emails.list({ limit: 100, status: "delivered" })) {
  console.log(email.id, email.status)
}

Get an email

GET/api/v1/emails/:id

Returns a single email wrapped in { "data": { … } }. The :id is the email's UUID — the same value POST /api/v1/send returns. Returns 404 not_found if the email doesn't exist or belongs to another workspace; a non-UUID id also returns 404.

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

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

"color:#ff7b72">const email = "color:#ff7b72">await ps.emails.get("550e8400-e29b-41d4-a716-446655440000")
console.log(email.status, email.delivered_at)

Errors

Errors use the standard envelope — unauthorized (401), invalid_field (400, for a bad status/type/cursor), and not_found (404). See the full Error codes reference for the canonical envelope.