GET /v1/admin/notifications/deliveries
List redacted notification delivery settlements
- operationId
listNotificationDeliveries- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：system_configuration.read
Description (from the contract)
Lists durable delivery state without recipient contacts, subject, body, deduplication keys, lease tokens, provider response bodies, or credentials. The cursor is stable for the selected filters.
Parameters
listNotificationDeliveries Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | No | — |
|---|
channel | query | string: email / sms | No | — |
|---|
state | query | string: pending / dispatching / retry_wait / accepted / unknown / delivered / permanent_failed / exhausted / cancelled | No | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string(uuid) | No | — |
|---|
Responses
listNotificationDeliveries Responses| Status | Description |
|---|
200 | Redacted delivery settlement page. Fields：items: array<DeliveryLog> next_cursor?: string(uuid) |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/notifications/delivery-history
List redacted immutable notification delivery facts
- operationId
listNotificationDeliveryHistory- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
Any of：system_configuration.read platform.admin
Description (from the contract)
Platform administrators with system_configuration.read or platform.admin may query all scopes or one exact scope. Session, membership and current permissions are revalidated before query validation and lookup. One row identifies one immutable outbox sequence, including anonymous recipients and replay generations. Filters combine with AND. Without from/to the complete history is queried. Each optional bound is inclusive; when both are supplied, to must be greater than from and the window at most 31 days. The current request uses one consistent database view for cursor validation, total_count and rows. Pages are ordered by observed_at, outbox_id and sequence descending. Cursors identify persisted facts and are validated against the current filters; they do not promise a snapshot across requests. Delivery history never includes message titles, bodies, full recipient contacts, provider response bodies, deduplication keys, lease tokens or credentials. New transport calls record only a masked recipient address and provider_call_started_at. A row sees only an observation in the same attempt through its own sequence; dispatch_started never reads a future settlement observation. Historical rows without observations remain null and are never backfilled from current user contacts. Message content retains its separate administrator message-query contract.
Parameters
listNotificationDeliveryHistory Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | No | Optional exact scope; omitted means all scopes for an authorized platform administrator. |
|---|
channel | query | string: email / sms | No | — |
|---|
state | query | string: pending / dispatching / retry_wait / accepted / unknown / delivered / permanent_failed / exhausted / cancelled | No | — |
|---|
result | query | string: success / failure | No | success means only delivered; failure means retry_wait, permanent_failed or exhausted. accepted, unknown, lease_unknown and cancelled are neither success nor failure. When state is also supplied, both filters must match; a contradiction returns an empty page. |
|---|
event_type | query | string | No | Exact persisted notification event type, not a legacy UI alias. |
|---|
user_id | query | string | No | Canonical lowercase nonzero UUID or positive decimal display ID, at most signed int64 maximum; filters recipients, not actors. |
|---|
message_id | query | string(uuid) | No | Exact immutable notification_events.id, shared by original and replay outboxes. |
|---|
from | query | string(date-time) | No | Inclusive observed_at lower bound, RFC3339 with optional fractional seconds. |
|---|
to | query | string(date-time) | No | Inclusive observed_at upper bound, RFC3339 with optional fractional seconds. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Returned outbox UUID and positive int32 fact sequence; must identify a fact satisfying the current filters. |
|---|
Responses
listNotificationDeliveryHistory Responses| Status | Description |
|---|
200 | A consistent current-request page and filtered total, with no cross-request snapshot guarantee. Fields：schema: string items: array<DeliveryHistoryFact> total_count: integer(int64) next_cursor?: string |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/notifications/messages
List the compatibility message projection
- operationId
listNotificationMessages- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：system_configuration.read
Description (from the contract)
Event-centric administrator view of member notification facts. Fields that are not backed by durable facts are returned as null. Site and package use the subject recorded when the event was raised; older package-monitor rows fall back to the monitor transition's exact subscription. Events raised without a site subject never match a site filter, and ownership is never inferred from current bindings. Titles, channel bodies and email_state/sms_state come from original generation-1 outbox facts (null = that channel was not generated); delivery replay does not duplicate message rows.
Parameters
listNotificationMessages Parameters| Name | In | Type | Required | Description |
|---|
scope_id | query | string(uuid) | No | — |
|---|
type | query | string | No | — |
|---|
user_id | query | string(uuid) | No | — |
|---|
package_id | query | string | No | Exact user subscription ID from a monitor transition; product IDs do not match. Unknown IDs return an empty page. |
|---|
site_id | query | string | No | Site recorded when the event was raised (notification_events.subject_site_id); events without a site subject never match. |
|---|
user | query | string | No | Recipient user by exact display ID or case-insensitive substring of username / display name (current values). |
|---|
package | query | string | No | User subscription by exact display ID or case-insensitive substring of the package name; events whose subscription no longer exists never match. |
|---|
site | query | string | No | Event-time site by exact display ID or case-insensitive substring of its current domain; events whose site no longer exists never match. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string(uuid) | No | — |
|---|
Responses
listNotificationMessages Responses| Status | Description |
|---|
200 | Versioned, event-centric compatibility projection of member notification facts. Fields：schema: string items: array<Message> next_cursor?: string(uuid) total: integer |
|---|
400 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
401 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
403 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
405 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
500 | Stable error envelope. Clients map code through locale resources and do not render message directly. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list