Transaktions-E-Mails per API senden

Kontrollierter Pilot für kleine, transaktionale JSON-Nachrichten mit eigener Absenderdomain, Idempotenz und Unterdrückungslisten.

Die Transaktionsmail-API nimmt kleine, anwendungsbezogene Nachrichten als JSON an. Eine eigene Absenderdomain, ein eng begrenzter Mail-Zugang und ein Idempotenzschlüssel trennen diesen Pfad von Benutzerkonten, Einladungen und anderen Obhut-Systemmails.

Kontrollierter Pilot

Dieser Versand ist noch nicht allgemein verfügbar. Obhut schaltet Domain, DKIM und Zugang erst nach einem gemeinsamen Pilot- und Missbrauchsreview frei. mail_not_enabled bedeutet, dass der Versand in der Zielumgebung noch nicht aktiviert ist.

Versand vorbereiten

Absenderdomain anlegen

Öffne im Dashboard E-Mail-Versand, lege die Domain an und veröffentliche den dort exakt angezeigten Ownership-TXT-Eintrag.

Ownership und DKIM prüfen

Starte die DNS-Prüfung. Für den Versand müssen die Domain als verifiziert und DKIM als aktiv angezeigt werden. Ein verifizierter Ownership-Eintrag allein reicht nicht aus.

Mail-Zugang erstellen

Erstelle einen Zugang für genau eine Domain oder für alle verifizierten Domains der Organisation. Das Token mit Präfix obhut_mail_ wird nur einmal angezeigt. Speichere es in deinem Secret Store und nie im Quellcode.

Erste Nachricht mit eindeutiger ID senden

Verwende je fachlichem Versandversuch einen stabilen Idempotency-Key. Wiederhole denselben Versuch nur mit demselben Schlüssel und unverändertem Body.

Anfrage

Der Maschinenendpunkt ist POST /v1/mail/send.

export OBHUT_MAIL_TOKEN='<einmal angezeigtes Token>'
export IDEMPOTENCY_KEY="$(openssl rand -hex 16)"

curl --fail-with-body https://api.obhut.io/v1/mail/send \
  --request POST \
  --header "Authorization: Bearer $OBHUT_MAIL_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "from": {
      "email": "rechnung@example.com",
      "name": "Example GmbH"
    },
    "replyTo": "service@example.com",
    "to": ["kunde@example.net"],
    "subject": "Ihre Rechnung 2026-0042",
    "text": "Guten Tag, Ihre Rechnung steht im Kundenportal bereit."
  }'

Erfolgreiche Annahme durch die Versandwarteschlange liefert 202:

{
  "submissionId": "41f65375-44ae-4cdd-9e9e-d6ffbc2c4021",
  "messageId": "<a1b2c3d4e5f6@example.com>",
  "state": "accepted",
  "recipientCount": 1
}

Die Antwort bestätigt die Annahme durch die Warteschlange, nicht die Zustellung im Empfängerpostfach und keine Platzierung im Posteingang.

Idempotenz und Wiederholungen

Der Idempotency-Key ist Pflicht und darf höchstens 128 Byte lang sein.

accepted: Die Warteschlange hat die Nachricht angenommen. Nicht erneut senden.
unknown: Die Verbindung brach in einem mehrdeutigen Moment ab. Derselbe Schlüssel liefert den gespeicherten Zustand und sendet nicht automatisch erneut.
failed mit HTTP 502: Die Annahme ist sicher fehlgeschlagen. Wiederhole den unveränderten Body mit demselben Schlüssel.
suppressed: Mindestens ein Empfänger steht auf der Unterdrückungsliste; die gesamte Nachricht wurde nicht versendet.

Ein anderer Body mit demselben Schlüssel liefert 409 idempotency_conflict. Bei einem Client-Timeout zuerst denselben Schlüssel erneut verwenden. Ein neuer Schlüssel kann eine doppelte Nachricht erzeugen.

Grenzen des Piloten

1 bis 10 Empfänger in to;
gesamter JSON-Body höchstens 256 KiB;
Betreff höchstens 255 Byte;
text und html jeweils höchstens 128 KiB, mindestens eines ist Pflicht;
Anzeigename höchstens 128 Zeichen;
keine Anhänge, CC/BCC, frei gesetzten Header, Templates, Kampagnen, Terminierung, Listen oder Marketingmails;
Standardgrenzen: 60 Nachrichten pro Minute je Zugang, 200 Empfänger pro Minute je Organisation, 1.000 Nachrichten und 5.000 Empfänger pro UTC-Tag.

HTTP 429 quota_exceeded kann nach dem nächsten Zeitfenster mit demselben Idempotenzschlüssel wiederholt werden. Höhere Grenzen benötigen ein erneutes Zustellbarkeits- und Missbrauchsreview.

Wichtige Fehler

HTTP	Fehler	Bedeutung
`400`	`idempotency_key_required`	Schlüssel fehlt oder ist zu lang.
`400`	`invalid_body`	JSON oder Feldgrenzen sind ungültig.
`400`	`domain_not_verified`	Die Absenderdomain ist nicht verifiziert.
`400`	`dkim_not_active`	Der veröffentlichte DKIM-Schlüssel ist noch nicht aktiv.
`401`	`unauthorized`	Token ist unbekannt, abgelaufen oder widerrufen.
`403`	`domain_out_of_scope`	Zugang ist nicht für diese Domain freigegeben.
`403`	`domain_suspended`	Versand für die Domain wurde gestoppt.
`409`	`idempotency_conflict`	Schlüssel wurde bereits mit anderem Body verwendet.
`413`	`payload_too_large`	Gesamter JSON-Body überschreitet 256 KiB.
`429`	`quota_exceeded`	Minuten- oder Tagesgrenze ist ausgeschöpft.
`502`	—	Versandwarteschlange hat die Nachricht sicher nicht angenommen.
`503`	`mail_not_enabled`	Pilot ist in dieser Umgebung nicht aktiviert.

Datenschutz und Unterdrückungen

Obhut speichert weder Betreff noch Body noch Empfängeradressen in den Versandmetadaten. Gespeichert werden der Zustand, Zähler, begrenzte Fehlercodes und für Unterdrückungen nur nicht umkehrbare Empfänger-Hashes. Hard Bounces und manuelle Beschwerden sperren den betroffenen Empfänger für weitere Versuche. Unter E-Mail-Versand kannst du eine Adresse prüfen, manuell unterdrücken oder nach dokumentierter Klärung wieder freigeben.