Skip to main content

Notification Template Endpoints

Summary​

The template group maps four operations under /notification-templates: list, create, update and test-render. Templates are versioned per tenant, key and channel.

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.

Template flow​

GET /notification-templates​

Lists templates with four optional filters: tenantId, key, channel and activeOnly. Filters are applied only when the corresponding value is supplied and non-blank, so an unfiltered call returns templates across all tenants. The channel filter is normalized before comparison. Results are ordered by template key, then channel, then descending version. Full template entities are returned.

POST /notification-templates​

Creates the next version for a tenant, key and channel triple.

Validation (verified): templateKey and channel must be non-blank, and channel must be a known channel; the failure message enumerates the known channels. Both failures return 400.

Versioning (verified): the handler reads the maximum existing version for the tenant, key and channel, defaults it to zero when none exists, and persists the new row at that value plus one. Existing versions are never mutated by this endpoint.

Tenant behavior (verified): a blank tenantId in the request body is stored as null, creating a global template rather than a tenant-specific one.

Defaults (verified): subject and body default to empty strings when omitted; isActive defaults to true.

Response: 201 Created with a Location header pointing at the new template and the created entity as the body.

PUT /notification-templates/{id:guid}​

Updates a template row in place. Unlike create, this endpoint does not create a new version.

Verified behavior: absent rows return 404 with a found flag. Present rows receive only the fields supplied as non-null — subject, body, locale, description — and isActive only when explicitly supplied. The updated timestamp is always stamped. The updated entity is returned.

POST /notification-templates/{id:guid}/test​

Renders a template with caller-supplied variables and optionally performs one live delivery.

Render-only path (verified): when send is not true, or when toAddress is blank, the handler renders the subject and body through ITemplateEngine.Render using the supplied variables (an empty dictionary when omitted) and returns the identifier, key, channel, version, rendered subject, rendered body and sent = false. Nothing is persisted.

Live-send path (verified): when send is true and toAddress is present, the handler persists an address-type recipient and a message row, resolves the channel's sender from the registry, and attempts exactly one delivery. Success marks the message sent and stamps the sent timestamp; failure marks it failed and records the error. Either way a delivery-attempt row is written recording attempt number one, the channel, the provider, the outcome and the timing. The response adds sent = true, the message identifier, the delivery status, the provider and any error.

Retry note: this endpoint performs a single attempt. It does not use the bounded retry loop that the dispatcher applies to event-driven delivery.

Verified absence​

There is no endpoint to delete a template, to deactivate a template other than through the update field, to list versions of a single template as a distinct resource, to promote a version, or to reset a template to a seeded default. The reset behavior exists only on the monolith compatibility surface.

Classification​

Implemented.

Requires confirmation​

Whether in-place update of a published version is intended alongside versioned create, and who may invoke the live-send path, require confirmation.

See Also​

Keywords​

  • Notification API
  • Template Endpoints
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Application/TemplateEngine.cs
  • microservices/src/notification-service/Channels/ChannelSenderRegistry.cs
  • microservices/src/notification-service/Domain/NotificationEntities.cs

Revision Information​

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