From 4a06b0bcb972a8d40c747685b17bca881e377399 Mon Sep 17 00:00:00 2001 From: Landon Hadre Date: Fri, 24 Jul 2026 14:20:58 -0400 Subject: [PATCH 1/3] init email self serve doc --- features/authentication/email.mdx | 213 ++++++++++++++++++++++++++++++ 1 file changed, 213 insertions(+) diff --git a/features/authentication/email.mdx b/features/authentication/email.mdx index f9a4775d..9b07d21a 100644 --- a/features/authentication/email.mdx +++ b/features/authentication/email.mdx @@ -405,3 +405,216 @@ turnkey request --host api.turnkey.com --path /public/v1/submit/set_organization } }' --organization ``` + +## Email delivery events + +Email self serve gives you visibility into email delivery events sent from your parent +organization. Use it to confirm whether an email was delivered, investigate delayed delivery, and +debug recipient-side failures such as bounces or complaints. + +- Parent organization scoped event history +- Per-recipient lookup by email address +- Optional filtering by event type +- Cursor-based pagination for delivery history + + +Email event lookup is scoped to the authenticated organization. If the request originated from a +sub-organization, the events are read from the parent organization. + + +### Event types + +Email events represent the delivery lifecycle reported by Turnkey's email provider. + +| Event type | Description | +| --- | --- | +| `Send` | The email was accepted for sending. | +| `Delivery` | The email was delivered to the recipient's mail server. | +| `DeliveryDelay` | Delivery was delayed and will be retried later. | +| `Bounce` | The recipient's mail server rejected the email. | +| `Complaint` | The recipient or mailbox provider reported the email as unwanted. | + +The Dashboard may display these in a more user-friendly form: + +| Dashboard status | API event type | Meaning | +| --- | --- | --- | +| Delivered | `Delivery` | The email was delivered to the recipient. | +| Delivery delayed | `DeliveryDelay` | Delivery was delayed by the email provider and may be retried. | +| Bounced | `Bounce` | The recipient's mail server rejected the email. | +| Complained | `Complaint` | The recipient or provider reported the message as unwanted. | + +### Before you begin + +- **Email is required.** Event lookup is recipient-based and requires an email address. +- **Email addresses are normalized.** The API normalizes `email` to lowercase server-side. +- **Results are newest first.** The most recent events are returned first. + +### How it works + + + + Provide the recipient email address you want to inspect. + + + Optionally pass `eventType` to show only sends, deliveries, delays, bounces, or complaints. + + + Use `paginationOptions.limit`, `paginationOptions.after`, and `paginationOptions.before` to + move through event history. + + + Use fields such as `eventType`, `timestamp`, `fromAddress`, `toAddress`, and `details` to + understand what happened to the message. + + + +### API reference + +This endpoint uses `HTTP POST` and requires a signed request body stamped with your API key. + +| Endpoint | Description | +| --- | --- | +| `POST /public/v1/query/list_email_events` | Retrieve email delivery events for a recipient | + +#### List email events + +Retrieves email delivery events for a recipient in the authenticated organization. + +#### Request body + +```json Request body +{ + "organizationId": "", + "email": "user@example.com", + "paginationOptions": { + "limit": "10" + } +} +``` + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `organizationId` | string | Yes | Customer organization ID. | +| `email` | string | Yes | Recipient email address to list events for. Normalized to lowercase server-side. | +| `eventType` | string | No | Exact event type filter. Useful values are `Send`, `Delivery`, `Bounce`, `DeliveryDelay`, and `Complaint`. | +| `paginationOptions.limit` | string | No | Maximum number of rows to return, up to `100`. | +| `paginationOptions.after` | string | No | Cursor event ID for fetching results after that event. | +| `paginationOptions.before` | string | No | Cursor event ID for fetching results before that event. | + +#### Response + +```json Response +{ + "emailEvents": [ + { + "id": "", + "organizationId": "", + "messageId": "", + "eventType": "Bounce", + "fromAddress": "no-reply@turnkey.com", + "toAddress": "user@example.com", + "senderTenant": "", + "timestamp": "1784840060374", + "createdAt": "1784840060374", + "details": { + "bounceType": "Permanent", + "bounceSubType": "General", + "diagnosticCode": "smtp; 550 5.1.1 user unknown", + "deliverySmtpResponse": "", + "deliveryProcessingTimeMillis": "0", + "deliveryDelayType": "" + } + } + ] +} +``` + +### Data types + +#### `EmailEvent` (response) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `id` | string | Yes | Unique email event ID. Use this value with pagination cursors. | +| `organizationId` | string | Yes | Organization associated with the event. | +| `messageId` | string | Yes | Email provider message ID. | +| `eventType` | string | Yes | Event type, such as `Delivery`, `Bounce`, or `DeliveryDelay`. | +| `fromAddress` | string | Yes | Sender email address. | +| `toAddress` | string | Yes | Recipient email address. | +| `senderTenant` | string | No | Sender tenant associated with the event. | +| `timestamp` | string | Yes | Event timestamp in milliseconds. | +| `createdAt` | string | Yes | Record creation timestamp in milliseconds. | +| `details` | object | No | Provider-specific delivery details. Fields depend on the event type. | + +#### `EmailEventDetails` (response) + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `bounceType` | string | No | Bounce category, such as `Permanent` or `Transient`. | +| `bounceSubType` | string | No | More specific bounce reason. | +| `diagnosticCode` | string | No | SMTP diagnostic code returned by the recipient's mail server. | +| `deliverySmtpResponse` | string | No | SMTP response for a delivery event. | +| `deliveryProcessingTimeMillis` | string | No | Time spent processing a delivery event, in milliseconds. | +| `deliveryDelayType` | string | No | Delay category for delayed delivery events. | + +#### `ListEmailEventsResponse` + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `emailEvents` | `EmailEvent[]` | Yes | Email delivery events matching the request. Results are ordered newest first. | + +### Troubleshooting + +#### Delivery delayed + +`DeliveryDelay` means the email provider could not complete delivery immediately. Delivery may be +retried later. Check the recipient address, mailbox provider status, and any details returned with +the event. + +#### Bounced + +`Bounce` means the recipient's mail server rejected the message. The `details` object may include +fields such as `bounceType`, `bounceSubType`, and `diagnosticCode` to explain the rejection. + +Permanent bounces usually indicate that the address is invalid, unreachable, or rejected by the +recipient's domain. Temporary failures may resolve after retry. + +#### Complained + +`Complaint` means the recipient or mailbox provider reported the email as unwanted or spam. +Complaint events are typically generated when a recipient marks the email as spam or when a +mailbox provider sends spam feedback. + +### Code examples + + + + ```shell + curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ + -H "Content-Type: application/json" \ + -H "X-Stamp: " \ + -d '{ + "organizationId": "", + "email": "user@example.com", + "paginationOptions": { + "limit": "10" + } + }' + ``` + + + ```shell + curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ + -H "Content-Type: application/json" \ + -H "X-Stamp: " \ + -d '{ + "organizationId": "", + "email": "user@example.com", + "eventType": "Bounce", + "paginationOptions": { + "limit": "10" + } + }' + ``` + + From 4d94a910d4d60d2aa06f3617fe25485209621cbc Mon Sep 17 00:00:00 2001 From: Graham Ritter Date: Fri, 24 Jul 2026 18:08:44 -0400 Subject: [PATCH 2/3] docs: add email delivery events as separate nested page Restructures the email delivery events content from the original PR into its own page under Email auth & recovery, with a rewritten intro, consolidated event types table, and API reference removed (to be linked from /api-reference/queries/). Co-Authored-By: Claude Opus 4.6 --- docs.json | 8 +- .../authentication/email-delivery-events.mdx | 75 ++++++ features/authentication/email.mdx | 215 +----------------- 3 files changed, 83 insertions(+), 215 deletions(-) create mode 100644 features/authentication/email-delivery-events.mdx diff --git a/docs.json b/docs.json index d573a462..70ad5916 100644 --- a/docs.json +++ b/docs.json @@ -318,7 +318,13 @@ { "group": "Auth methods", "pages": [ - "features/authentication/email", + { + "group": "Email auth & recovery", + "pages": [ + "features/authentication/email", + "features/authentication/email-delivery-events" + ] + }, "features/authentication/social-logins", "features/authentication/sms", "features/authentication/otp-migration-guide", diff --git a/features/authentication/email-delivery-events.mdx b/features/authentication/email-delivery-events.mdx new file mode 100644 index 00000000..aa1ded98 --- /dev/null +++ b/features/authentication/email-delivery-events.mdx @@ -0,0 +1,75 @@ +--- +title: "Email delivery events" +description: "Monitor email delivery status, investigate delays, and debug bounces or complaints using the Turnkey Dashboard or API." +--- + +Turnkey provides visibility into email delivery events sent from your organization. Use the Dashboard or the [`list_email_events`](/api-reference/queries/list-email-events) API to look up delivery status by recipient, confirm whether an email was delivered, investigate delays, and debug failures such as bounces or complaints. + +- Per-recipient lookup by email address +- Optional filtering by event type +- Cursor-based pagination for large delivery histories + + +Email delivery events are stored at the parent organization level. Queries made from a sub-organization will return events for the parent organization. + + +## Event types + +| Event type | Dashboard label | Description | +| --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `Send` | — | The email was accepted for sending. | +| `Delivery` | Delivered | The email was delivered to the recipient's mail server. | +| `DeliveryDelay` | Delivery delayed | Delivery was delayed and may be retried. Check the recipient address and the mailbox provider's status page. | +| `Bounce` | Bounced | The recipient's mail server rejected the email. Permanent bounces indicate an invalid or unreachable address. Transient bounces may resolve after retry. | +| `Complaint` | Complained | The recipient or mailbox provider reported the email as spam. Typically generated when a recipient marks the message as spam. | + +## Querying delivery events + + + + Provide the recipient email address you want to inspect. + + + Pass an `eventType` to narrow results to sends, deliveries, delays, bounces, or complaints. + + + Use `paginationOptions.limit`, `paginationOptions.after`, and `paginationOptions.before` to page through event history. Results are returned newest first. + + + Review fields such as `eventType`, `timestamp`, `fromAddress`, `toAddress`, and `details` to understand what happened to the message. + + + +## Code examples + + + + ```shell + curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ + -H "Content-Type: application/json" \ + -H "X-Stamp: " \ + -d '{ + "organizationId": "", + "email": "user@example.com", + "paginationOptions": { + "limit": "10" + } + }' + ``` + + + ```shell + curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ + -H "Content-Type: application/json" \ + -H "X-Stamp: " \ + -d '{ + "organizationId": "", + "email": "user@example.com", + "eventType": "Bounce", + "paginationOptions": { + "limit": "10" + } + }' + ``` + + diff --git a/features/authentication/email.mdx b/features/authentication/email.mdx index 9b07d21a..37bbae6e 100644 --- a/features/authentication/email.mdx +++ b/features/authentication/email.mdx @@ -1,5 +1,5 @@ --- -title: "Email auth & recovery" +title: "Overview" description: "Email Authentication enables users to authenticate and recover their Turnkey accounts using email-based verification. There are two methods of email authentication:" --- @@ -405,216 +405,3 @@ turnkey request --host api.turnkey.com --path /public/v1/submit/set_organization } }' --organization ``` - -## Email delivery events - -Email self serve gives you visibility into email delivery events sent from your parent -organization. Use it to confirm whether an email was delivered, investigate delayed delivery, and -debug recipient-side failures such as bounces or complaints. - -- Parent organization scoped event history -- Per-recipient lookup by email address -- Optional filtering by event type -- Cursor-based pagination for delivery history - - -Email event lookup is scoped to the authenticated organization. If the request originated from a -sub-organization, the events are read from the parent organization. - - -### Event types - -Email events represent the delivery lifecycle reported by Turnkey's email provider. - -| Event type | Description | -| --- | --- | -| `Send` | The email was accepted for sending. | -| `Delivery` | The email was delivered to the recipient's mail server. | -| `DeliveryDelay` | Delivery was delayed and will be retried later. | -| `Bounce` | The recipient's mail server rejected the email. | -| `Complaint` | The recipient or mailbox provider reported the email as unwanted. | - -The Dashboard may display these in a more user-friendly form: - -| Dashboard status | API event type | Meaning | -| --- | --- | --- | -| Delivered | `Delivery` | The email was delivered to the recipient. | -| Delivery delayed | `DeliveryDelay` | Delivery was delayed by the email provider and may be retried. | -| Bounced | `Bounce` | The recipient's mail server rejected the email. | -| Complained | `Complaint` | The recipient or provider reported the message as unwanted. | - -### Before you begin - -- **Email is required.** Event lookup is recipient-based and requires an email address. -- **Email addresses are normalized.** The API normalizes `email` to lowercase server-side. -- **Results are newest first.** The most recent events are returned first. - -### How it works - - - - Provide the recipient email address you want to inspect. - - - Optionally pass `eventType` to show only sends, deliveries, delays, bounces, or complaints. - - - Use `paginationOptions.limit`, `paginationOptions.after`, and `paginationOptions.before` to - move through event history. - - - Use fields such as `eventType`, `timestamp`, `fromAddress`, `toAddress`, and `details` to - understand what happened to the message. - - - -### API reference - -This endpoint uses `HTTP POST` and requires a signed request body stamped with your API key. - -| Endpoint | Description | -| --- | --- | -| `POST /public/v1/query/list_email_events` | Retrieve email delivery events for a recipient | - -#### List email events - -Retrieves email delivery events for a recipient in the authenticated organization. - -#### Request body - -```json Request body -{ - "organizationId": "", - "email": "user@example.com", - "paginationOptions": { - "limit": "10" - } -} -``` - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `organizationId` | string | Yes | Customer organization ID. | -| `email` | string | Yes | Recipient email address to list events for. Normalized to lowercase server-side. | -| `eventType` | string | No | Exact event type filter. Useful values are `Send`, `Delivery`, `Bounce`, `DeliveryDelay`, and `Complaint`. | -| `paginationOptions.limit` | string | No | Maximum number of rows to return, up to `100`. | -| `paginationOptions.after` | string | No | Cursor event ID for fetching results after that event. | -| `paginationOptions.before` | string | No | Cursor event ID for fetching results before that event. | - -#### Response - -```json Response -{ - "emailEvents": [ - { - "id": "", - "organizationId": "", - "messageId": "", - "eventType": "Bounce", - "fromAddress": "no-reply@turnkey.com", - "toAddress": "user@example.com", - "senderTenant": "", - "timestamp": "1784840060374", - "createdAt": "1784840060374", - "details": { - "bounceType": "Permanent", - "bounceSubType": "General", - "diagnosticCode": "smtp; 550 5.1.1 user unknown", - "deliverySmtpResponse": "", - "deliveryProcessingTimeMillis": "0", - "deliveryDelayType": "" - } - } - ] -} -``` - -### Data types - -#### `EmailEvent` (response) - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `id` | string | Yes | Unique email event ID. Use this value with pagination cursors. | -| `organizationId` | string | Yes | Organization associated with the event. | -| `messageId` | string | Yes | Email provider message ID. | -| `eventType` | string | Yes | Event type, such as `Delivery`, `Bounce`, or `DeliveryDelay`. | -| `fromAddress` | string | Yes | Sender email address. | -| `toAddress` | string | Yes | Recipient email address. | -| `senderTenant` | string | No | Sender tenant associated with the event. | -| `timestamp` | string | Yes | Event timestamp in milliseconds. | -| `createdAt` | string | Yes | Record creation timestamp in milliseconds. | -| `details` | object | No | Provider-specific delivery details. Fields depend on the event type. | - -#### `EmailEventDetails` (response) - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `bounceType` | string | No | Bounce category, such as `Permanent` or `Transient`. | -| `bounceSubType` | string | No | More specific bounce reason. | -| `diagnosticCode` | string | No | SMTP diagnostic code returned by the recipient's mail server. | -| `deliverySmtpResponse` | string | No | SMTP response for a delivery event. | -| `deliveryProcessingTimeMillis` | string | No | Time spent processing a delivery event, in milliseconds. | -| `deliveryDelayType` | string | No | Delay category for delayed delivery events. | - -#### `ListEmailEventsResponse` - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `emailEvents` | `EmailEvent[]` | Yes | Email delivery events matching the request. Results are ordered newest first. | - -### Troubleshooting - -#### Delivery delayed - -`DeliveryDelay` means the email provider could not complete delivery immediately. Delivery may be -retried later. Check the recipient address, mailbox provider status, and any details returned with -the event. - -#### Bounced - -`Bounce` means the recipient's mail server rejected the message. The `details` object may include -fields such as `bounceType`, `bounceSubType`, and `diagnosticCode` to explain the rejection. - -Permanent bounces usually indicate that the address is invalid, unreachable, or rejected by the -recipient's domain. Temporary failures may resolve after retry. - -#### Complained - -`Complaint` means the recipient or mailbox provider reported the email as unwanted or spam. -Complaint events are typically generated when a recipient marks the email as spam or when a -mailbox provider sends spam feedback. - -### Code examples - - - - ```shell - curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ - -H "Content-Type: application/json" \ - -H "X-Stamp: " \ - -d '{ - "organizationId": "", - "email": "user@example.com", - "paginationOptions": { - "limit": "10" - } - }' - ``` - - - ```shell - curl -X POST https://api.turnkey.com/public/v1/query/list_email_events \ - -H "Content-Type: application/json" \ - -H "X-Stamp: " \ - -d '{ - "organizationId": "", - "email": "user@example.com", - "eventType": "Bounce", - "paginationOptions": { - "limit": "10" - } - }' - ``` - - From 013369484fc8ca356d7a51d34c6edf961feb26cd Mon Sep 17 00:00:00 2001 From: Landon Hadre Date: Sat, 1 Aug 2026 14:29:00 -0400 Subject: [PATCH 3/3] slight update on dashboard label --- features/authentication/email-delivery-events.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/features/authentication/email-delivery-events.mdx b/features/authentication/email-delivery-events.mdx index aa1ded98..3a3af330 100644 --- a/features/authentication/email-delivery-events.mdx +++ b/features/authentication/email-delivery-events.mdx @@ -18,10 +18,10 @@ Email delivery events are stored at the parent organization level. Queries made | Event type | Dashboard label | Description | | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Send` | — | The email was accepted for sending. | -| `Delivery` | Delivered | The email was delivered to the recipient's mail server. | -| `DeliveryDelay` | Delivery delayed | Delivery was delayed and may be retried. Check the recipient address and the mailbox provider's status page. | -| `Bounce` | Bounced | The recipient's mail server rejected the email. Permanent bounces indicate an invalid or unreachable address. Transient bounces may resolve after retry. | -| `Complaint` | Complained | The recipient or mailbox provider reported the email as spam. Typically generated when a recipient marks the message as spam. | +| `Delivery` | Delivered | The email was delivered to the recipient's mail server. | +| `DeliveryDelay` | Delayed | Delivery was delayed and may be retried. Check the recipient address and the mailbox provider's status page. | +| `Bounce` | Bounced | The recipient's mail server rejected the email. Permanent bounces indicate an invalid or unreachable address. Transient bounces may resolve after retry. | +| `Complaint` | Complaint | The recipient or mailbox provider reported the email as spam. Typically generated when a recipient marks the message as spam. | ## Querying delivery events @@ -33,7 +33,7 @@ Email delivery events are stored at the parent organization level. Queries made Pass an `eventType` to narrow results to sends, deliveries, delays, bounces, or complaints. - Use `paginationOptions.limit`, `paginationOptions.after`, and `paginationOptions.before` to page through event history. Results are returned newest first. + Results are ordered newest first. Use `paginationOptions.limit` to set the page size. For the next page, pass the last event ID as after. For the previous page, pass the first event ID as before. Review fields such as `eventType`, `timestamp`, `fromAddress`, `toAddress`, and `details` to understand what happened to the message.