API

REST-API-Referenz

Alle Endpunkte, Parameter, Beispiel-Anfragen und -Antworten. Authentifizierung: API-Schlüssel (Bearer).

Schnelles Beispiel

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Willkommen",
    "html": "<h1>Hallo!</h1>"
  }'

Der API-Schlüssel wird im Panel → Tab Entwickler abgerufen. Für Produktions- und Testumgebung werden separate Schlüssel mit eigenem Scope empfohlen.

Authentifizierung

Jede Anfrage trägt den Header Authorization: Bearer YOUR_API_KEY. Der Schlüssel wird im Panel erstellt, bei der Erstellung einmalig angezeigt und danach gehasht. Geht ein Schlüssel verloren, erzeugen Sie einen neuen und widerrufen den alten — mit dem Widerruf ist der alte Schlüssel sofort deaktiviert.

  • Scope-basierte Berechtigung: 30 Scopes (send · campaign · template · webhook · domain · ...). Ein Schlüssel nutzt nur die Bereiche, die Sie freigeben.
  • IP-Allowlist: Produktionsschlüssel lassen sich auf bestimmte IP-/CIDR-Bereiche beschränken.
  • Zeitlimit: Schlüsseln lässt sich eine TTL zuweisen; nach Ablauf sind sie automatisch ungültig.
  • Audit-Log: Jede Schlüsselnutzung wird mit Timestamp + Endpunkt + Ergebnis protokolliert.

Idempotency-Key

Verwenden Sie bei POST-Anfragen den Header Idempotency-Key — eine zweite Anfrage mit demselben Schlüssel liefert die erste Antwort erneut, ohne doppelten Versand. UUIDv4 empfohlen; der Schlüssel wird 24 Stunden gespeichert. 

curl https://api.sendnomi.com/v1/messages \
  -H "Authorization: Bearer sn_live_•••" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-..." \
  ...

Fehlerformat

Alle Fehlerantworten kommen im selben Umschlag — Code + Meldung + anfragespezifisches Detail:

{
  "error": {
    "code":    "invalid_recipient",
    "message": "Empfängeradresse entspricht nicht der Formatregel",
    "field":   "to",
    "request_id": "req_01HX8K..."
  }
}

HTTP-Statuscodes folgen RFC 7231. Temporäre Fehler sind 5xx + Retry-After; permanente 4xx-Fehler unterliegen keinem Retry.

Rate-Limit

Das Limit hängt von Ihrem Plan ab und wird im Panel in Echtzeit angezeigt. Jede Antwort enthält die Header:

  • X-RateLimit-Limit · erlaubte Anfragen im Fenster
  • X-RateLimit-Remaining · verbleibendes Anfrage-Kontingent
  • X-RateLimit-Reset · Zeitpunkt, zu dem das Fenster zurückgesetzt wird (Unix-Epoch)

Erhalten Sie einen 429, warten Sie die im Header Retry-After angegebene Zeit ab. Die SDKs erledigen das automatisch.

Versionierung

Die Version ist in der URL verpflichtend (/v1/). Der Wechsel auf eine neue Version kommt mit einem Deprecation-Fenster von 12 Monaten + Changelog-Hinweis. Breaking Changes erfolgen nie stillschweigend — sobald ein veralteter Endpunkt genutzt wird, liefert die Antwort einen Warn-Header.

Endpunkt-Liste

  • POST /v1/messages Einzelne oder Massen-E-Mail senden.
  • GET /v1/messages/{id} Status einer bestimmten Nachricht abfragen.
  • GET /v1/messages Nachrichtenliste, mit Filterung und Paginierung.
  • POST /v1/templates Neue Vorlage erstellen (Handlebars + Liquid Mix).
  • GET /v1/templates/{id} Vorlagen-Detail.
  • POST /v1/suppressions Adresse zur Suppression-Liste hinzufügen.
  • GET /v1/suppressions Suppression-Liste.
  • POST /v1/webhooks Webhook-Endpunkt registrieren.
  • GET /v1/events Ereignis-Stream (sent, delivered, opened, clicked, bounced, complained).
  • GET /v1/domains Ihre verifizierten Domains.

OpenAPI-3.1-Spezifikation: /v1/openapi.json — für den Import in IDE / Postman. Jeder Endpunkt ist mit allen Parametern, Beispiel-Anfrage und Antwortschema dokumentiert.