primitivedotdev 2.1.0__tar.gz → 2.3.0__tar.gz

{primitivedotdev-2.1.0 → primitivedotdev-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: primitivedotdev
-Version: 2.1.0
+Version: 2.3.0
 Summary: Official Primitive Python SDK for webhook handling and API access
 Project-URL: Homepage, https://primitive.dev
 Project-URL: Repository, https://github.com/primitivedotdev/sdks
@@ -173,6 +173,27 @@ client.forward(
 )
 ```
 
+### Errors and rate limits
+
+A failed call raises `primitive.PrimitiveAPIError`. It carries `status_code`,
+`code`, `request_id`, `details`, and `retry_after` (the `Retry-After` header in
+seconds, when the server sent one). On a 429 it also carries `rate_limit`, a
+`primitive.RateLimit` with `limit`, `remaining`, `reset` (Unix seconds) and
+`policy` from the `ratelimit-*` headers. These describe the limiter that
+rejected the request, with its own window, which may be a send cap
+(`1000;w=3600`) rather than the API request budget. `rate_limit` is `None` when
+a 429 carried only `Retry-After`; wait for `retry_after` either way.
+
+```python
+from primitive import PrimitiveAPIError
+
+try:
+    client.send(from_email=sender, to=to, subject="Hi", body_text="Hello")
+except PrimitiveAPIError as err:
+    if err.status_code == 429:
+        print(err.retry_after, err.rate_limit and err.rate_limit.policy)
+```
+
 ### Per-call request options
 
 `send`, `reply`, `forward` (and their `a*` async variants) accept the same
@@ -604,11 +625,49 @@ page = search_emails(
 Turning `include_facets` off skips the facet aggregation entirely. Search text
 containing a NUL character is rejected with a 400 validation error.
 
+`q` takes words, `"quoted phrases"` and `field:value` filters, and every
+term must match. An upper-case `OR` between two text terms (words, phrases,
+`subject:` and `body:` terms) accepts either and binds tighter than the
+implicit AND, so `acme invoice OR receipt` means `acme` and either `invoice` or
+`receipt`. `OR` cannot join filters such as `from:`, and there is no `NOT`;
+either is a 400 validation error, as is a leading or trailing `OR`. To search
+for the word `OR` or `NOT` itself, write it in lower case or in double quotes.
+Facet values are ordered by count descending, ties by value in byte order, and
+`by_sender` and `by_domain` keep the first 20.
+
+Date filters such as `date_from` and `date_to` take an ISO 8601 timestamp with
+`Z` or a numeric UTC offset (`2026-10-02T00:00:00-04:00`); a time with no zone,
+or a bare date, is rejected.
+
 Upgrading to 2.0: `EmailSearchMeta.total` is now typed `int | None`. It is
 `None` only when the request sets `count=SearchEmailsCount.FALSE`; type-checked
 code that treats it as an `int` needs a `None` check. Search results also gain
 the required `thread_id` and `direction` fields.
 
+### Sent email webhook events
+
+Endpoints can also receive events about mail you send: `sent_email.accepted`, `sent_email.delivered`, `sent_email.failed` and `sent_email.completed`. They are opt-in: an endpoint receives them only when its `rules.event_types` lists them (with the CLI, `primitive endpoints create --url <url> --event-types sent_email.*`). An endpoint that lists them and also handles inbound mail must keep `email.received` in the list.
+
+Each body carries `event`, and is validated against the `sent_email.*` JSON schema when parsed. Each recipient (To, Cc and Bcc) of a send gets exactly one `sent_email.delivered` or `sent_email.failed` with `scope` `"recipient"`, for up to 100 recipients. Mail relay sends with more recipients report the rest in roll-ups (`scope` `"message"`, `reason` `"rollup"`), sends recorded before per-recipient results can report one legacy message-level result (`reason` `"legacy_message_result"`), and relay recipients delivered inside the sender's own mail system get no event and are listed in `summary.not_relayed_recipients`. So do not wait for a per-recipient event per address: use `sent_email.completed`, which carries the totals once every recipient is final. Deduplicate on the event `id` (equal to the `X-Webhook-Id` header), and check that `delivery.endpoint_id` is the endpoint that received the request.
+
+```python
+from primitive import (
+    handle_webhook_event,
+    is_sent_email_completed_event,
+    is_sent_email_recipient_result_event,
+)
+
+event = handle_webhook_event(body=raw_body, headers=request.headers, secret=secret)
+
+if is_sent_email_recipient_result_event(event) and event.event == "sent_email.failed":
+    # event.recipient.type is "to", "cc" or "bcc"
+    print(event.recipient.address, event.outcome.smtp_enhanced_status_code)
+elif is_sent_email_completed_event(event):
+    print(event.summary.recipient_count, event.summary.delivered, event.summary.failed)
+```
+
+Parsed events are Pydantic models (`SentEmailAcceptedEvent`, `SentEmailRecipientResultEvent`, `SentEmailRollupResultEvent`, `SentEmailLegacyMessageResultEvent`, `SentEmailCompletedEvent`). `validate_sent_email_event` / `safe_validate_sent_email_event` validate an already parsed body, and the schema is exported as `sent_email_event_json_schema`. An `email.bounced` event's `email.analysis.bounce` carries `sent_email_id` (the send the bounce belongs to, or None when it could not be linked) and `failed_recipients` (every failed address, up to 100).
+
 ### Payment and interaction webhook events
 
 Webhooks are not email-only. The same endpoint also receives `payment.*` settlement notifications and `interaction.x402.*` events from the x402-over-email flow. The event name is carried in the **`X-Webhook-Event` header** for every family. The body is sent verbatim with no envelope, so it is the header (not a body field) that names the event: an `email.*` body carries `event`, a `payment.*` body carries the name in `type`, and an `interaction.*` body is just `{"interaction": {...}}` with no event/type field at all.
@@ -639,6 +698,7 @@ elif is_interaction_x402_event(event):
 The full catalog of header values is exported as the `WEBHOOK_EVENT_TYPES` tuple:
 
 - `email.received`, `email.bounced`, `email.tls_report`, `email.dmarc_report`, `email.dmarc_failure`
+- `sent_email.accepted`, `sent_email.delivered`, `sent_email.failed`, `sent_email.completed` (opt-in)
 - `payment.settled`, `payment.failed`
 - `interaction.x402.challenge`, `interaction.x402.payment`, `interaction.x402.settled`, `interaction.x402.rejected`, `interaction.x402.declined`, `interaction.x402.expired`, `interaction.x402.verify_timeout`
 - `interaction.ack.received`, `interaction.ack.requested`, `interaction.ack.acked`, `interaction.ack.canceled`, `interaction.ack.expired`

{primitivedotdev-2.1.0 → primitivedotdev-2.3.0}/README.md

@@ -143,6 +143,27 @@ client.forward(
 )
 ```
 
+### Errors and rate limits
+
+A failed call raises `primitive.PrimitiveAPIError`. It carries `status_code`,
+`code`, `request_id`, `details`, and `retry_after` (the `Retry-After` header in
+seconds, when the server sent one). On a 429 it also carries `rate_limit`, a
+`primitive.RateLimit` with `limit`, `remaining`, `reset` (Unix seconds) and
+`policy` from the `ratelimit-*` headers. These describe the limiter that
+rejected the request, with its own window, which may be a send cap
+(`1000;w=3600`) rather than the API request budget. `rate_limit` is `None` when
+a 429 carried only `Retry-After`; wait for `retry_after` either way.
+
+```python
+from primitive import PrimitiveAPIError
+
+try:
+    client.send(from_email=sender, to=to, subject="Hi", body_text="Hello")
+except PrimitiveAPIError as err:
+    if err.status_code == 429:
+        print(err.retry_after, err.rate_limit and err.rate_limit.policy)
+```
+
 ### Per-call request options
 
 `send`, `reply`, `forward` (and their `a*` async variants) accept the same
@@ -574,11 +595,49 @@ page = search_emails(
 Turning `include_facets` off skips the facet aggregation entirely. Search text
 containing a NUL character is rejected with a 400 validation error.
 
+`q` takes words, `"quoted phrases"` and `field:value` filters, and every
+term must match. An upper-case `OR` between two text terms (words, phrases,
+`subject:` and `body:` terms) accepts either and binds tighter than the
+implicit AND, so `acme invoice OR receipt` means `acme` and either `invoice` or
+`receipt`. `OR` cannot join filters such as `from:`, and there is no `NOT`;
+either is a 400 validation error, as is a leading or trailing `OR`. To search
+for the word `OR` or `NOT` itself, write it in lower case or in double quotes.
+Facet values are ordered by count descending, ties by value in byte order, and
+`by_sender` and `by_domain` keep the first 20.
+
+Date filters such as `date_from` and `date_to` take an ISO 8601 timestamp with
+`Z` or a numeric UTC offset (`2026-10-02T00:00:00-04:00`); a time with no zone,
+or a bare date, is rejected.
+
 Upgrading to 2.0: `EmailSearchMeta.total` is now typed `int | None`. It is
 `None` only when the request sets `count=SearchEmailsCount.FALSE`; type-checked
 code that treats it as an `int` needs a `None` check. Search results also gain
 the required `thread_id` and `direction` fields.
 
+### Sent email webhook events
+
+Endpoints can also receive events about mail you send: `sent_email.accepted`, `sent_email.delivered`, `sent_email.failed` and `sent_email.completed`. They are opt-in: an endpoint receives them only when its `rules.event_types` lists them (with the CLI, `primitive endpoints create --url <url> --event-types sent_email.*`). An endpoint that lists them and also handles inbound mail must keep `email.received` in the list.
+
+Each body carries `event`, and is validated against the `sent_email.*` JSON schema when parsed. Each recipient (To, Cc and Bcc) of a send gets exactly one `sent_email.delivered` or `sent_email.failed` with `scope` `"recipient"`, for up to 100 recipients. Mail relay sends with more recipients report the rest in roll-ups (`scope` `"message"`, `reason` `"rollup"`), sends recorded before per-recipient results can report one legacy message-level result (`reason` `"legacy_message_result"`), and relay recipients delivered inside the sender's own mail system get no event and are listed in `summary.not_relayed_recipients`. So do not wait for a per-recipient event per address: use `sent_email.completed`, which carries the totals once every recipient is final. Deduplicate on the event `id` (equal to the `X-Webhook-Id` header), and check that `delivery.endpoint_id` is the endpoint that received the request.
+
+```python
+from primitive import (
+    handle_webhook_event,
+    is_sent_email_completed_event,
+    is_sent_email_recipient_result_event,
+)
+
+event = handle_webhook_event(body=raw_body, headers=request.headers, secret=secret)
+
+if is_sent_email_recipient_result_event(event) and event.event == "sent_email.failed":
+    # event.recipient.type is "to", "cc" or "bcc"
+    print(event.recipient.address, event.outcome.smtp_enhanced_status_code)
+elif is_sent_email_completed_event(event):
+    print(event.summary.recipient_count, event.summary.delivered, event.summary.failed)
+```
+
+Parsed events are Pydantic models (`SentEmailAcceptedEvent`, `SentEmailRecipientResultEvent`, `SentEmailRollupResultEvent`, `SentEmailLegacyMessageResultEvent`, `SentEmailCompletedEvent`). `validate_sent_email_event` / `safe_validate_sent_email_event` validate an already parsed body, and the schema is exported as `sent_email_event_json_schema`. An `email.bounced` event's `email.analysis.bounce` carries `sent_email_id` (the send the bounce belongs to, or None when it could not be linked) and `failed_recipients` (every failed address, up to 100).
+
 ### Payment and interaction webhook events
 
 Webhooks are not email-only. The same endpoint also receives `payment.*` settlement notifications and `interaction.x402.*` events from the x402-over-email flow. The event name is carried in the **`X-Webhook-Event` header** for every family. The body is sent verbatim with no envelope, so it is the header (not a body field) that names the event: an `email.*` body carries `event`, a `payment.*` body carries the name in `type`, and an `interaction.*` body is just `{"interaction": {...}}` with no event/type field at all.
@@ -609,6 +668,7 @@ elif is_interaction_x402_event(event):
 The full catalog of header values is exported as the `WEBHOOK_EVENT_TYPES` tuple:
 
 - `email.received`, `email.bounced`, `email.tls_report`, `email.dmarc_report`, `email.dmarc_failure`
+- `sent_email.accepted`, `sent_email.delivered`, `sent_email.failed`, `sent_email.completed` (opt-in)
 - `payment.settled`, `payment.failed`
 - `interaction.x402.challenge`, `interaction.x402.payment`, `interaction.x402.settled`, `interaction.x402.rejected`, `interaction.x402.declined`, `interaction.x402.expired`, `interaction.x402.verify_timeout`
 - `interaction.ack.received`, `interaction.ack.requested`, `interaction.ack.acked`, `interaction.ack.canceled`, `interaction.ack.expired`

{primitivedotdev-2.1.0 → primitivedotdev-2.3.0}/json-schema/email-received-event.schema.json

@@ -798,7 +798,19 @@
         },
         "failed_recipient": {
           "type": ["string", "null"],
-          "description": "The recipient address that failed, if the report identifies one."
+          "description": "The first failed recipient, as the bounce wrote it, if the report identifies one. The status and diagnostic fields describe this recipient."
+        },
+        "failed_recipients": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "type": "string"
+          },
+          "description": "Every address the bounce reports as failed, lowercased and deduplicated, up to 100. Includes both the final and the original recipient when an alias or forward rewrote the address. Empty when the bounce names no usable address. Absent on payloads built before this field existed."
+        },
+        "sent_email_id": {
+          "type": ["string", "null"],
+          "description": "The id of your send this bounce belongs to (the same id as `GET /v1/sent-emails/{id}`), or null when it could not be linked. Linking is best effort: a bounce links only when it quotes the original Message-ID of a send from your organization and one of its failed recipients was on that send. Absent on payloads built before this field existed."
         },
         "smtp_code": {
           "type": ["integer", "null"],

primitivedotdev-2.3.0/json-schema/sent-email-event.schema.json

@@ -0,0 +1,431 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$ref": "#/definitions/SentEmailEvent",
+  "definitions": {
+    "SentEmailEvent": {
+      "title": "SentEmailEvent",
+      "description": "The body of a sent_email.* webhook delivery: events about mail you send through Primitive. A separate payload family from the inbound email.* events, with its own version. Keys that do not apply to an event are absent, not null. Fields marked open take values beyond the ones listed; treat unknown values as newer additions.",
+      "oneOf": [
+        { "$ref": "#/definitions/SentEmailAcceptedEvent" },
+        { "$ref": "#/definitions/SentEmailRecipientResultEvent" },
+        { "$ref": "#/definitions/SentEmailRollupResultEvent" },
+        { "$ref": "#/definitions/SentEmailLegacyMessageResultEvent" },
+        { "$ref": "#/definitions/SentEmailCompletedEvent" }
+      ]
+    },
+    "SentEmailEventDelivery": {
+      "type": "object",
+      "description": "This webhook attempt. Not the email's delivery.",
+      "required": ["endpoint_id", "attempt", "attempted_at"],
+      "properties": {
+        "endpoint_id": {
+          "type": "string",
+          "description": "The endpoint this attempt was sent to. Every endpoint is signed with the organization's secret, so check this is the endpoint that received the request."
+        },
+        "attempt": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1 for the first attempt, higher on retries."
+        },
+        "attempted_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When this attempt was sent."
+        }
+      }
+    },
+    "SentEmailTag": {
+      "type": "object",
+      "required": ["name", "value"],
+      "properties": {
+        "name": { "type": "string" },
+        "value": { "type": "string" }
+      }
+    },
+    "SentEmailRelay": {
+      "type": "object",
+      "description": "The mail relay that took a relay send.",
+      "required": ["hostname", "via"],
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "description": "The Primitive relay that took the message."
+        },
+        "via": { "type": "string", "const": "mail_relay" }
+      }
+    },
+    "SentEmailRecord": {
+      "type": "object",
+      "description": "The send's current state when this attempt was made, with the same fields as GET /v1/sent-emails/{id}. Not a snapshot of when the event was created, and not this event's result.",
+      "required": [
+        "id",
+        "status",
+        "status_changed_at",
+        "created_at",
+        "source",
+        "from_address",
+        "to_addresses",
+        "cc",
+        "bcc",
+        "recipient_count",
+        "subject",
+        "message_id",
+        "thread_id",
+        "tags",
+        "relay"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The sent email id. For mail relay sends there is no API call, and the id first appears in these events."
+        },
+        "status": {
+          "type": "string",
+          "description": "The send's overall status (open): queued, scheduled, submitted_to_agent, deferred, delivered, bounced, wait_timeout, unknown, agent_failed, gate_denied, canceled. Never a recipient's result."
+        },
+        "status_changed_at": { "type": "string", "format": "date-time" },
+        "created_at": { "type": "string", "format": "date-time" },
+        "source": {
+          "type": "string",
+          "description": "How the mail entered Primitive (open): api or mail_relay."
+        },
+        "from_address": { "type": "string" },
+        "to_addresses": {
+          "type": ["array", "null"],
+          "items": { "type": "string" }
+        },
+        "cc": {
+          "type": ["array", "null"],
+          "items": { "type": "string" },
+          "description": "Null when the send had no Cc recipients."
+        },
+        "bcc": {
+          "type": ["array", "null"],
+          "items": { "type": "string" },
+          "description": "Null when the send had no Bcc recipients. On a mail relay send, every recipient no To or Cc header names."
+        },
+        "recipient_count": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "description": "Every recipient of the send, To, Cc and Bcc together, each address counted once. On a relay send, recipients the relay never received (mail kept inside the sender's own mail system) get no result events."
+        },
+        "subject": { "type": ["string", "null"] },
+        "message_id": { "type": ["string", "null"] },
+        "thread_id": { "type": ["string", "null"] },
+        "tags": {
+          "type": ["array", "null"],
+          "description": "The tags given on the send request. Null or empty when there are none; relay sends carry none.",
+          "items": { "$ref": "#/definitions/SentEmailTag" }
+        },
+        "relay": {
+          "description": "The mail relay that took a relay send, or null for API sends.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/SentEmailRelay" }]
+        }
+      }
+    },
+    "SentEmailRecipientType": {
+      "type": "string",
+      "enum": ["to", "cc", "bcc"],
+      "description": "The list that names the recipient. On a mail relay send every hidden recipient is bcc."
+    },
+    "SentEmailFailureKind": {
+      "type": "string",
+      "enum": ["rejected", "expired"],
+      "description": "rejected: the receiving server refused the message permanently. expired: it kept asking to retry until the retry period ran out. Closed for this version."
+    },
+    "SentEmailRecipient": {
+      "type": "object",
+      "required": ["address", "type"],
+      "properties": {
+        "address": { "type": "string" },
+        "type": { "$ref": "#/definitions/SentEmailRecipientType" }
+      }
+    },
+    "SentEmailOutcome": {
+      "type": "object",
+      "description": "This event's result.",
+      "required": [
+        "result",
+        "failure_kind",
+        "smtp_response_code",
+        "smtp_enhanced_status_code",
+        "smtp_response_text",
+        "at"
+      ],
+      "properties": {
+        "result": { "type": "string", "enum": ["delivered", "failed"] },
+        "failure_kind": {
+          "description": "Null when delivered.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/SentEmailFailureKind" }]
+        },
+        "smtp_response_code": { "type": ["integer", "null"] },
+        "smtp_enhanced_status_code": { "type": ["string", "null"] },
+        "smtp_response_text": {
+          "type": ["string", "null"],
+          "description": "Text from a third-party server: untrusted, never render it as HTML."
+        },
+        "at": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "When the result was recorded."
+        }
+      }
+    },
+    "SentEmailRollupOutcome": {
+      "type": "object",
+      "description": "A roll-up's result. Roll-ups carry no SMTP answer.",
+      "required": [
+        "result",
+        "failure_kind",
+        "smtp_response_code",
+        "smtp_enhanced_status_code",
+        "smtp_response_text",
+        "at"
+      ],
+      "properties": {
+        "result": { "type": "string", "enum": ["delivered", "failed"] },
+        "failure_kind": {
+          "description": "Null when delivered.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/definitions/SentEmailFailureKind" }]
+        },
+        "smtp_response_code": { "type": "null" },
+        "smtp_enhanced_status_code": { "type": "null" },
+        "smtp_response_text": { "type": "null" },
+        "at": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "When the result was recorded."
+        }
+      }
+    },
+    "SentEmailRolledUpFailure": {
+      "type": "object",
+      "required": [
+        "address",
+        "type",
+        "smtp_response_code",
+        "smtp_enhanced_status_code",
+        "smtp_response_text",
+        "at"
+      ],
+      "properties": {
+        "address": { "type": "string" },
+        "type": { "$ref": "#/definitions/SentEmailRecipientType" },
+        "smtp_response_code": { "type": ["integer", "null"] },
+        "smtp_enhanced_status_code": { "type": ["string", "null"] },
+        "smtp_response_text": {
+          "type": ["string", "null"],
+          "description": "Text from a third-party server: untrusted, never render it as HTML."
+        },
+        "at": { "type": ["string", "null"], "format": "date-time" }
+      }
+    },
+    "SentEmailFailedByKind": {
+      "type": "object",
+      "required": ["rejected", "expired"],
+      "properties": {
+        "rejected": { "type": "integer", "minimum": 0 },
+        "expired": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "SentEmailCompletedSummary": {
+      "type": "object",
+      "description": "Totals over every recipient of the send: delivered + failed + not_relayed == recipient_count (when not_relayed is not null).",
+      "required": [
+        "recipient_count",
+        "delivered",
+        "failed",
+        "failed_by_kind",
+        "not_relayed",
+        "not_relayed_recipients"
+      ],
+      "properties": {
+        "recipient_count": { "type": "integer", "minimum": 1 },
+        "delivered": { "type": "integer", "minimum": 0 },
+        "failed": { "type": "integer", "minimum": 0 },
+        "failed_by_kind": { "$ref": "#/definitions/SentEmailFailedByKind" },
+        "not_relayed": {
+          "type": ["integer", "null"],
+          "minimum": 0,
+          "description": "Mail relay sends: To or Cc recipients that never reached the relay because the mailbox provider delivered them internally. Primitive has no result for them. 0 for every other send. Null for a relay send recorded before Primitive kept the relay's envelope, when this cannot be known."
+        },
+        "not_relayed_recipients": {
+          "type": ["array", "null"],
+          "description": "The not_relayed recipients. [] when there are none; null when not_relayed is null.",
+          "items": { "$ref": "#/definitions/SentEmailRecipient" }
+        }
+      }
+    },
+    "SentEmailAcceptedEvent": {
+      "type": "object",
+      "description": "Exactly once for every send Primitive accepted, whatever state the send has reached when the event is created.",
+      "required": ["id", "event", "version", "created_at", "delivery", "sent_email"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The event id. The same on every retry and at every endpoint, and equal to the X-Webhook-Id header. Deduplicate on it."
+        },
+        "event": { "type": "string", "const": "sent_email.accepted" },
+        "version": {
+          "type": "string",
+          "description": "The version of the sent_email.* payload family. Not an event date."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the event happened, as far as Primitive knows it: a result's time for result events, the last result's time for sent_email.completed."
+        },
+        "delivery": { "$ref": "#/definitions/SentEmailEventDelivery" },
+        "sent_email": { "$ref": "#/definitions/SentEmailRecord" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["scope"] },
+          { "required": ["recipient"] },
+          { "required": ["recipient_count"] },
+          { "required": ["reason"] },
+          { "required": ["outcome"] },
+          { "required": ["recipients"] },
+          { "required": ["summary"] }
+        ]
+      }
+    },
+    "SentEmailRecipientResultEvent": {
+      "type": "object",
+      "description": "One recipient's final result: exactly one delivered or failed event per recipient, for the first 100 recipients.",
+      "required": ["id", "event", "version", "created_at", "delivery", "sent_email", "scope", "recipient", "outcome"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The event id. The same on every retry and at every endpoint, and equal to the X-Webhook-Id header. Deduplicate on it."
+        },
+        "event": { "type": "string", "enum": ["sent_email.delivered", "sent_email.failed"] },
+        "version": {
+          "type": "string",
+          "description": "The version of the sent_email.* payload family. Not an event date."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the event happened, as far as Primitive knows it: a result's time for result events, the last result's time for sent_email.completed."
+        },
+        "delivery": { "$ref": "#/definitions/SentEmailEventDelivery" },
+        "sent_email": { "$ref": "#/definitions/SentEmailRecord" },
+        "scope": { "type": "string", "const": "recipient" },
+        "recipient": { "$ref": "#/definitions/SentEmailRecipient" },
+        "outcome": { "$ref": "#/definitions/SentEmailOutcome" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["recipient_count"] },
+          { "required": ["reason"] },
+          { "required": ["recipients"] },
+          { "required": ["summary"] }
+        ]
+      }
+    },
+    "SentEmailRollupResultEvent": {
+      "type": "object",
+      "description": "Recipients past the first 100 (mail relay sends only). A failed roll-up lists the recipients it covers in recipients, each listed on exactly one failed roll-up; a delivered roll-up is a count, sent once every rolled-up recipient is final, and carries no recipients.",
+      "required": ["id", "event", "version", "created_at", "delivery", "sent_email", "scope", "recipient", "recipient_count", "reason", "outcome"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The event id. The same on every retry and at every endpoint, and equal to the X-Webhook-Id header. Deduplicate on it."
+        },
+        "event": { "type": "string", "enum": ["sent_email.delivered", "sent_email.failed"] },
+        "version": {
+          "type": "string",
+          "description": "The version of the sent_email.* payload family. Not an event date."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the event happened, as far as Primitive knows it: a result's time for result events, the last result's time for sent_email.completed."
+        },
+        "delivery": { "$ref": "#/definitions/SentEmailEventDelivery" },
+        "sent_email": { "$ref": "#/definitions/SentEmailRecord" },
+        "scope": { "type": "string", "const": "message" },
+        "recipient": { "type": "null" },
+        "recipient_count": { "type": "integer", "minimum": 1 },
+        "reason": { "type": "string", "const": "rollup" },
+        "outcome": { "$ref": "#/definitions/SentEmailRollupOutcome" },
+        "recipients": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Present on failed roll-ups only: the recipients this roll-up covers.",
+          "items": { "$ref": "#/definitions/SentEmailRolledUpFailure" }
+        }
+      },
+      "if": { "properties": { "event": { "const": "sent_email.failed" } } },
+      "then": { "required": ["recipients"] },
+      "else": { "not": { "required": ["recipients"] } },
+      "not": { "required": ["summary"] }
+    },
+    "SentEmailLegacyMessageResultEvent": {
+      "type": "object",
+      "description": "Only for sends recorded before Primitive kept each recipient's result: one result for the recipient_count recipients it covers.",
+      "required": ["id", "event", "version", "created_at", "delivery", "sent_email", "scope", "recipient", "recipient_count", "reason", "outcome"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The event id. The same on every retry and at every endpoint, and equal to the X-Webhook-Id header. Deduplicate on it."
+        },
+        "event": { "type": "string", "enum": ["sent_email.delivered", "sent_email.failed"] },
+        "version": {
+          "type": "string",
+          "description": "The version of the sent_email.* payload family. Not an event date."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the event happened, as far as Primitive knows it: a result's time for result events, the last result's time for sent_email.completed."
+        },
+        "delivery": { "$ref": "#/definitions/SentEmailEventDelivery" },
+        "sent_email": { "$ref": "#/definitions/SentEmailRecord" },
+        "scope": { "type": "string", "const": "message" },
+        "recipient": { "type": "null" },
+        "recipient_count": { "type": "integer", "minimum": 1 },
+        "reason": { "type": "string", "const": "legacy_message_result" },
+        "outcome": { "$ref": "#/definitions/SentEmailOutcome" }
+      },
+      "not": {
+        "anyOf": [{ "required": ["recipients"] }, { "required": ["summary"] }]
+      }
+    },
+    "SentEmailCompletedEvent": {
+      "type": "object",
+      "description": "Once per send, after its last result event, when every recipient has a final result.",
+      "required": ["id", "event", "version", "created_at", "delivery", "sent_email", "summary"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "The event id. The same on every retry and at every endpoint, and equal to the X-Webhook-Id header. Deduplicate on it."
+        },
+        "event": { "type": "string", "const": "sent_email.completed" },
+        "version": {
+          "type": "string",
+          "description": "The version of the sent_email.* payload family. Not an event date."
+        },
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the event happened, as far as Primitive knows it: a result's time for result events, the last result's time for sent_email.completed."
+        },
+        "delivery": { "$ref": "#/definitions/SentEmailEventDelivery" },
+        "sent_email": { "$ref": "#/definitions/SentEmailRecord" },
+        "summary": { "$ref": "#/definitions/SentEmailCompletedSummary" }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["scope"] },
+          { "required": ["recipient"] },
+          { "required": ["recipient_count"] },
+          { "required": ["reason"] },
+          { "required": ["outcome"] },
+          { "required": ["recipients"] }
+        ]
+      }
+    }
+  }
+}