SOT Learning Portal

Email notification API

The Smart Operations Toolkit sends localized emails based on templates. Applications request notifications through Kafka; templates are managed through REST and MCP. For the template fields and placeholders, see Email templates. For authentication, tenants and general conventions, see Concepts.

All endpoints of the template REST API with their parameters and data structures: Email notification API reference.

Requesting a notification

An application publishes a request to the Kafka topic nfs.request (with the environment-specific topic prefix). Format: JSON, version 1.

{
  "tenantId": "t1",
  "requestId": "0b8f3b7e-6d62-4b52-9b0f-3a2f6f3c9e11",
  "contextId": "cm-rule-triggered",
  "placeholders": {
    "ruleName": "Spindle temperature too high",
    "device": "Milling Center 04",
    "measuringPoint": "temperature",
    "severity": "warning",
    "time": "2026-10-16T10:15:00Z",
    "triggeredValue": "81.4"
  },
  "recipients": [
    { "address": "ada@example.com", "language": "en", "placeholders": { "name": "Ada" } },
    { "address": "bob@example.com", "language": "de" }
  ]
}
Field Description

tenantId

Tenant of the request.

requestId

UUID that the sending application generates. Use the same ID when you publish the same request again. Every recipient of a request receives the email only once.

contextId

Purpose of the notification. Selects the template, for example cm-rule-triggered.

placeholders

Values for all recipients.

recipients

1 to 100 recipients with address and language (en or de). Optional placeholders per recipient override the shared values.

Delivery

  • The template is selected by contextId and the language of the recipient.

  • One email is sent per distinct mailbox. Duplicates such as Ada <ada@example.com> and ada@example.com are sent once.

  • Every tenant can send at most 100 emails per hour (safety cap).

  • The outcome per recipient is logged for 7 days: sent or failed with the reason template_not_found, placeholder_missing, send_failed or tenant_rate_limited.

  • Requests that violate the contract are skipped and not stored.

  • Email addresses and placeholder values are never logged or stored.

Template REST API

Base URL:

https://<sot-host>/nfs/api/v1/tenants/{tenantId}
Path Method Purpose Permission

/templates

GET

List templates. Filters: filter[context_id], filter[language], filter[origin]; sortBy, page, pageSize

templates:read

/templates

POST

Create a template. 409 if a template for the context ID and language exists.

templates:write

/templates/{id}

GET

Read a template

templates:read

/templates/{id}

PATCH

Change subject or body. Context ID and language cannot be changed.

templates:write

/templates/{id}

DELETE

Delete a template

templates:delete

Subject and body use the Go text/template syntax, for example {{.device}} or {{if .name}}…{{end}}. The syntax is checked when the template is saved.

MCP server

https://<sot-host>/nfs/tenants/{tenantId}/mcp
Tool Purpose Permission

sot-nfs_query_templates

List templates or read one template

templates:read

sot-nfs_manage_template

Create or change a template

templates:write

sot-nfs_delete_template

Delete a template

templates:delete

API für E-Mail-Benachrichtigungen

Das Smart Operations Toolkit versendet lokalisierte E-Mails auf Basis von Vorlagen. Anwendungen fordern Benachrichtigungen über Kafka an; die Vorlagen werden über REST und MCP verwaltet. Felder und Platzhalter der Vorlagen: siehe E-Mail-Vorlagen. Authentifizierung, Tenants und allgemeine Konventionen: siehe Konzepte.

Alle Endpunkte der Vorlagen-REST-API mit ihren Parametern und Datenstrukturen: Referenz der API für E-Mail-Benachrichtigungen.

Benachrichtigung anfordern

Eine Anwendung veröffentlicht eine Anfrage im Kafka-Topic nfs.request (mit dem umgebungsspezifischen Topic-Präfix). Format: JSON, Version 1.

{
  "tenantId": "t1",
  "requestId": "0b8f3b7e-6d62-4b52-9b0f-3a2f6f3c9e11",
  "contextId": "cm-rule-triggered",
  "placeholders": {
    "ruleName": "Spindle temperature too high",
    "device": "Milling Center 04",
    "measuringPoint": "temperature",
    "severity": "warning",
    "time": "2026-10-16T10:15:00Z",
    "triggeredValue": "81.4"
  },
  "recipients": [
    { "address": "ada@example.com", "language": "en", "placeholders": { "name": "Ada" } },
    { "address": "bob@example.com", "language": "de" }
  ]
}
Feld Beschreibung

tenantId

Tenant der Anfrage.

requestId

UUID, die die sendende Anwendung erzeugt. Beim erneuten Veröffentlichen derselben Anfrage dieselbe ID verwenden. Jeder Empfänger einer Anfrage erhält die E-Mail nur einmal.

contextId

Zweck der Benachrichtigung. Bestimmt die Vorlage, zum Beispiel cm-rule-triggered.

placeholders

Werte für alle Empfänger.

recipients

1 bis 100 Empfänger mit address und language (en oder de). Optionale placeholders je Empfänger überschreiben die gemeinsamen Werte.

Zustellung

  • Die Vorlage wird über contextId und die Sprache des Empfängers ausgewählt.

  • Je eindeutigem Postfach wird eine E-Mail versendet. Duplikate wie Ada <ada@example.com> und ada@example.com erhalten die E-Mail einmal.

  • Jeder Tenant kann höchstens 100 E-Mails pro Stunde versenden (Sicherheitsgrenze).

  • Das Ergebnis je Empfänger wird 7 Tage lang protokolliert: sent oder failed mit dem Grund template_not_found, placeholder_missing, send_failed oder tenant_rate_limited.

  • Anfragen, die gegen den Vertrag verstoßen, werden übersprungen und nicht gespeichert.

  • E-Mail-Adressen und Platzhalterwerte werden nie protokolliert oder gespeichert.

REST-API für Vorlagen

Basis-URL:

https://<sot-host>/nfs/api/v1/tenants/{tenantId}
Pfad Methode Zweck Berechtigung

/templates

GET

Vorlagen auflisten. Filter: filter[context_id], filter[language], filter[origin]; sortBy, page, pageSize

templates:read

/templates

POST

Vorlage anlegen. 409, wenn bereits eine Vorlage für Kontext-ID und Sprache existiert.

templates:write

/templates/{id}

GET

Vorlage lesen

templates:read

/templates/{id}

PATCH

Betreff oder Text ändern. Kontext-ID und Sprache lassen sich nicht ändern.

templates:write

/templates/{id}

DELETE

Vorlage löschen

templates:delete

Betreff und Text verwenden die Syntax von Go text/template, zum Beispiel {{.device}} oder {{if .name}}…{{end}}. Beim Speichern der Vorlage wird die Syntax geprüft.

MCP-Server

https://<sot-host>/nfs/tenants/{tenantId}/mcp
Tool Zweck Berechtigung

sot-nfs_query_templates

Vorlagen auflisten oder eine Vorlage lesen

templates:read

sot-nfs_manage_template

Vorlage anlegen oder ändern

templates:write

sot-nfs_delete_template

Vorlage löschen

templates:delete
Diese Seite bearbeiten Edit this page

Feedback on this pageFeedback zu dieser Seite