Skip to main content

Notification Inbox Endpoints

Summary​

The inbox group maps two operations under /notifications: a filtered in-app message list and a read-state transition. Both are registered in MapInboxEndpoints.

Audience​

API consumers, engineers, architects, QA, support and security reviewers.

Reference Content​

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

GET /notifications/my​

Returns the in-app messages for a recipient.

Query parameters (verified): recipientRef (required), recipientType (optional), tenantId (optional), unreadOnly (optional), take (optional).

Resolution order (verified): the handler first resolves recipient rows whose TenantId equals the supplied tenantId and whose ExternalRef equals recipientRef, optionally narrowed by RecipientType. When no recipient row matches, the handler returns an empty array, not a 404.

Messages are then filtered to the resolved recipient ids and the in-app channel only. When unreadOnly is true, messages already in the read status are excluded. Results are ordered newest-first and the page size is clamped to the range 1–500 with a default of 100.

Response shape (verified): an anonymous projection per message exposing the identifier, tenant, template key, event type, channel, subject, body, status, creation timestamp, read timestamp, and a computed isRead flag. The full message entity is not returned by this endpoint.

Validation: a blank or missing recipientRef returns 400 with a message object.

Tenant behavior: the tenantId value is compared directly. A request that omits it matches recipient rows whose tenant is null, rather than matching every tenant.

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

Marks a single in-app message read.

Verified behavior: the message is loaded by identifier alone. When absent, the handler returns 404 with a found flag. When present and not already read, the status is set to the read value, the read timestamp is stamped, an audit row is appended at the read stage carrying the message's tenant, event, event type and correlation identifier, and the change is saved. When the message is already read the handler saves nothing and returns the current state, making the call idempotent.

Response shape (verified): an anonymous projection of the identifier, status and read timestamp.

Authorization note: the lookup is not constrained by recipient or tenant. Any caller that knows a message identifier can mark it read.

Channel scope​

GET /notifications/my filters to the in-app channel. Email, SMS and WhatsApp messages are not readable through this endpoint; they are visible only through the administration endpoints.

Verified absence​

There is no endpoint to mark all messages read, to delete a message, to archive a message, or to list a recipient's messages across channels.

Classification​

Implemented.

Requires confirmation​

How recipientRef is expected to be derived and trusted by callers requires confirmation.

See Also​

Keywords​

  • Notification API
  • Inbox Endpoints
  • Draft API documentation

Source References​

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

Revision Information​

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