Skip to main content

Notification Administration Endpoints

Summary​

Seven operations under /notifications expose message state, delivery attempts, manual retry, the failed queue, idempotency lookup, the audit trail and aggregate counts. They are registered in MapAdminAndTestEndpoints and tagged notifications-admin.

Audience​

Engineers, architects, QA, support, security reviewers and DevOps engineers.

Reference Content​

The verified reference material for this topic is set out in the sections below.

GET /notifications/{id:guid}​

Returns one message entity by identifier, or 404 with a found flag when absent. The query is read-only and unscoped by tenant.

GET /notifications/{id:guid}/attempts​

Returns every delivery-attempt row recorded for the message, ordered ascending by attempt number. An unknown message identifier yields an empty array rather than a 404, because the handler filters attempts without first confirming the message exists.

Each attempt row carries the attempt number, channel, provider, outcome status, any error text and the start and completion timestamps.

POST /notifications/{id:guid}/retry​

Re-drives delivery for a message through INotificationDispatcher.RetryMessageAsync, then reloads the message to report its resulting state.

Verified behavior: the dispatcher call happens first and returns a delivered flag. The handler then loads the message; when it is absent, 404 is returned with a found flag. Otherwise the response projects the identifier, the resulting status, the accumulated attempt count and the delivered flag.

Scope: the handler does not require the message to be in a failed state. Any message identifier may be submitted.

GET /notifications/failed​

Returns messages whose status is failed, ordered newest-first, with take clamped to the range 1–500 and defaulting to 100. The query spans all tenants; there is no tenant filter on this endpoint.

GET /notifications/processed/{eventId:guid}​

Idempotency lookup. Returns the processed-event row for a consumed event identifier, or 404 with a processed flag when the event has not been recorded. This is the read side of the duplicate-suppression mechanism described in the technical processing pipeline.

GET /notifications/audit​

Queries the append-only audit trail with three optional filters — eventId, correlationId and messageId — applied only when supplied. Results are ordered by occurrence descending with take clamped to the range 1–1000 and defaulting to 200.

An unfiltered call returns the most recent audit rows across all tenants and all events.

GET /notifications/stats​

Returns a single anonymous projection of eight counts computed with separate count queries: templates, recipients, messages, sent messages, failed messages, read messages, processed events and delivery attempts. The counts are platform-wide; no tenant filter is applied and no filter parameter is accepted.

Tenant and authorization posture​

None of these seven endpoints declares authentication or authorization, and none accepts or applies a tenant filter. The failed queue, audit trail and statistics therefore expose cross-tenant operational data to any caller that can reach the service. This is recorded as a limitation rather than a recommendation.

Verified absence​

There is no endpoint to bulk-retry the failed queue, to purge or archive messages, to delete audit rows, to filter statistics by tenant or date, or to export any of these collections.

Classification​

Implemented; cross-tenant exposure is a verified limitation.

Requires confirmation​

Whether these endpoints are intended to remain reachable outside an operator context, and whether tenant filtering is planned, require confirmation.

See Also​

Keywords​

  • Notification API
  • Administration Endpoints
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Application/NotificationDispatcher.cs
  • microservices/src/notification-service/Domain/NotificationEntities.cs

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-21
  • Review cycle: Quarterly