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..3a3af330 --- /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` | 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 + + + + Provide the recipient email address you want to inspect. + + + Pass an `eventType` to narrow results to sends, deliveries, delays, bounces, or complaints. + + + 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. + + + +## 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 f9a4775d..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:" ---