diff --git a/src/content/docs/email-service/platform/event-subscriptions.mdx b/src/content/docs/email-service/platform/event-subscriptions.mdx new file mode 100644 index 00000000000..9dbf4c779bb --- /dev/null +++ b/src/content/docs/email-service/platform/event-subscriptions.mdx @@ -0,0 +1,20 @@ +--- +title: Event subscriptions +description: Subscribe to Email Sending lifecycle events with Queues. +pcx_content_type: reference +sidebar: + order: 10 +head: + - tag: title + content: Event subscriptions +products: + - email-service +--- + +import { Render } from "~/components"; + + + +## Available Email Sending events + + diff --git a/src/content/docs/queues/event-subscriptions/events-schemas.mdx b/src/content/docs/queues/event-subscriptions/events-schemas.mdx index 8ef19407ef6..d5fb99894f1 100644 --- a/src/content/docs/queues/event-subscriptions/events-schemas.mdx +++ b/src/content/docs/queues/event-subscriptions/events-schemas.mdx @@ -25,6 +25,10 @@ This page provides a comprehensive reference of available event sources and thei +### Email Sending + + + ### R2 diff --git a/src/content/partials/queues/event-subscriptions/email-sending-events.mdx b/src/content/partials/queues/event-subscriptions/email-sending-events.mdx new file mode 100644 index 00000000000..dfc7595167b --- /dev/null +++ b/src/content/partials/queues/event-subscriptions/email-sending-events.mdx @@ -0,0 +1,242 @@ +Email Sending event subscriptions publish outbound transactional email lifecycle events for messages sent from an enabled sending domain. Each subscription is scoped to one sending domain: either the zone apex, such as `example.com`, or a verified sending subdomain, such as `send.example.com`. + +Email Routing events, including inbound forwards, replies, Worker-emitted routing events, and deliveries to verified routing recipients, are not published as Email Sending events. + +#### `message.delivered` + +Triggered when the recipient mail server accepts the message. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.delivered", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "example.com" + }, + "payload": { + "eventId": "0190d0c4-7e9a-7b3c-9f12-1a2b3c4d5e6f", + "messageId": "0101018f7d0c4d9a-msg-deadbeef", + "sender": "noreply@example.com", + "recipient": "user@example.net", + "subject": "Welcome", + "terminal": true, + "delivery": { + "status": "delivered", + "provider": "gmail", + "deliveryTimeMs": 1234, + "smtpStatusCode": "250", + "smtpEnhancedStatusCode": "2.0.0", + "smtpResponse": "250 2.0.0 OK 1714820445 a1b2c3 - gsmtp" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +``` + +#### `message.deferred` + +Triggered when a temporary delivery failure occurs and delivery retries are still pending. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.deferred", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "send.example.com" + }, + "payload": { + "eventId": "0190d0c4-7e9b-7714-9004-11f0b6d9a341", + "messageId": "0101018f7d0c4d9a-msg-deferred", + "sender": "receipts@send.example.com", + "recipient": "user@example.net", + "subject": "Your receipt", + "terminal": false, + "delivery": { + "status": "deferred", + "provider": "external_smtp", + "deliveryTimeMs": 2143, + "smtpStatusCode": "451", + "smtpEnhancedStatusCode": "4.2.0", + "smtpResponse": "451 4.2.0 Temporary mailbox error" + }, + "bounce": { + "type": "soft", + "classification": "temporary_failure", + "reason": "451 4.2.0 Temporary mailbox error" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +``` + +#### `message.bounced` + +Triggered when a permanent bounce occurs, or when temporary delivery retries are exhausted. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.bounced", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "send.example.com" + }, + "payload": { + "eventId": "0190d0c4-7ea1-7af2-8b88-c1d2e3f4a5b6", + "messageId": "0101018f7d0c4d9a-msg-bounced", + "sender": "receipts@send.example.com", + "recipient": "user@example.net", + "subject": "Your receipt", + "terminal": true, + "delivery": { + "status": "bounced", + "provider": "external_smtp", + "deliveryTimeMs": 2143, + "smtpStatusCode": "550", + "smtpEnhancedStatusCode": "5.1.1", + "smtpResponse": "550 5.1.1 User unknown" + }, + "bounce": { + "type": "hard", + "classification": "permanent_failure", + "reason": "550 5.1.1 User unknown" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +``` + +#### `message.failed` + +Triggered when an internal or non-SMTP delivery error occurs. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.failed", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "example.com" + }, + "payload": { + "eventId": "0190d0c4-81c1-7bc6-9344-829cd9001a12", + "messageId": "0101018f7d0c4d9a-msg-failed", + "sender": "noreply@example.com", + "recipient": "user@example.net", + "subject": "Welcome", + "terminal": true, + "delivery": { + "status": "failed" + }, + "failure": { + "reason": "delivery_failed" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +``` + +#### `message.rejected` + +Triggered when the message is rejected before delivery by policy, including suppression, validation rejection, or spam rejection. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.rejected", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "example.com" + }, + "payload": { + "eventId": "0190d0c4-830a-77e5-8fa0-8d10f4e8dc8b", + "messageId": "0101018f7d0c4d9a-msg-rejected", + "sender": "noreply@example.com", + "recipient": "user@example.net", + "subject": "Welcome", + "terminal": true, + "delivery": { + "status": "rejected" + }, + "rejection": { + "reason": "suppressed", + "party": "recipient", + "detail": "Recipient is suppressed" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +``` + +#### `message.complained` + +Triggered when a delivered message is marked as spam by the recipient through a feedback loop. + +**Example:** + +```json +{ + "type": "cf.email.sending.message.complained", + "source": { + "type": "email.sending", + "zoneId": "023e105f4ecef8ad9ca31a8372d0c353", + "domain": "send.example.com" + }, + "payload": { + "eventId": "0190d0c4-9f01-7c44-b2a1-aabbccddeeff", + "messageId": "0101018f7d0c4d9a-msg-complained", + "sender": "news@send.example.com", + "recipient": "user@example.net", + "terminal": true, + "delivery": { + "status": "complained" + }, + "complaint": { + "type": "abuse" + } + }, + "metadata": { + "accountId": "f9f79265f388666de8122cfb508d7776", + "eventSubscriptionId": "1830c4bb612e43c3af7f4cada31fbf3f", + "eventSchemaVersion": 1, + "eventTimestamp": "2026-06-01T02:48:57.132Z" + } +} +```