Skip to content

4. API integrieren ​

API-Key, Idempotenz, Annahme/202, Hold/409, Statusabfrage.

Ziel ​

Eure Anwendung sendet Nachrichten über die Dispatch-API, erkennt zuverlässig den Zustand jeder Nachricht und verarbeitet die ausgehenden Webhooks korrekt.

Voraussetzung ​

Ein eingerichteter Kanal (Kapitel 3) mit mindestens einer Sende-Identität sowie ein API-Key aus dem Kundenbereich (API-Keys → Erstellen).

Basis-URL ​

Alle Endpunkte dieses Kapitels liegen unter https://dispatch.host-universe.com/api — POST /v1/send unten meint also vollständig POST https://dispatch.host-universe.com/api/v1/send.

Authentifizierung ​

Jeder Aufruf unter /v1/* braucht den Header:

Authorization: Bearer dispatch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Der Key wird beim Anlegen genau einmal im Klartext angezeigt — sicher speichern, er lässt sich nicht erneut abrufen. Fehlt der Header, ist der Key ungültig, abgelaufen oder widerrufen, antwortet Dispatch einheitlich mit 401 — aus Sicherheitsgründen absichtlich ohne Unterscheidung, welcher der drei Fälle vorliegt. Ablaufdatum und Widerruf eines Keys legt ausschließlich Host Universe fest (Kapitel 11); ihr selbst vergebt beim Anlegen nur eine Bezeichnung.

Nachricht senden — POST /v1/send ​

Pflichtangaben: recipient, subject (max. 998 Zeichen), mindestens eines von body_html/body_text, sowie sending_identity_id (oder stream_area mit bereits gebundener Identität). Zusätzlich immer Pflicht: der Header Idempotency-Key — eine von euch vergebene, pro Sendeversuch eindeutige Kennung (z. B. eine UUID). Setzt ihr external_campaign_reference (eigene Kampagne mit listenweiter Abmeldung statt Sammel-Versandzeile), wird zusätzlich campaign_name Pflicht — ein für euch lesbarer Anzeigename der Kampagne.

POST https://dispatch.host-universe.com/api/v1/send
Authorization: Bearer dispatch_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Idempotency-Key: 6f6b1e2e-7b31-4b8a-9b1a-2c9a6a5e2b3d
Content-Type: application/json

{
  "recipient": "kunde@beispiel-mandant.test",
  "sending_identity_id": 12,
  "subject": "Ihre Bestellung ist unterwegs",
  "body_html": "<p>Vielen Dank für Ihre Bestellung.</p>",
  "external_campaign_reference": "bestellbestaetigung",
  "campaign_name": "Bestellbestätigung"
}

Antwort immer 202, nie ein Erfolgs-Fehlschlag-Mix:

json
{
  "message_id": 483920,
  "status": "accepted",
  "campaign_id": 67,
  "replay": false
}

status in dieser Antwort ist der Annahmestatus: accepted, held oder failed. Danach durchläuft die Nachricht weitere, nur über GET /v1/message/{id} (Kapitel 9) oder Webhooks (Kapitel 10) sichtbare Zustände — u. a. sent, deferred (vorübergehend nicht zustellbar, Kapitel 7), delivered, bounced, complained. held heißt: die Nachricht wartet auf freies Kontingent oder auf ein Empfänger-Gate (Kapitel 8) — sie geht automatisch weiter, sobald der Grund entfällt, ihr müsst nichts erneut senden. Wartet sie länger als 3 Tage auf Kontingent, stellt Dispatch sie nicht mehr zu: Sie endet als failed mit bounce_code: "expired:max-hold-days" (siehe „Gegendruck“ unten). failed kommt sofort in der Antwort, wenn der Empfänger gesperrt ist (bounce_code: "suppressed:<grund>", Kapitel 7) — die Nachricht wird gar nicht erst zugestellt versucht.

Backpressure statt Fehler ​

Übersteigt eine Nachricht das Tages-/Warmup-Kontingent (Kapitel 6), kommt sie mit status: "held" an — kein Fehler. Wollt ihr stattdessen sofort wissen, ob Platz war, setzt accept_hold: false: dann antwortet Dispatch 409 und erzeugt keine Nachricht, damit ihr den Empfänger anderweitig zustellen könnt:

json
{
  "code": "dispatch_capacity_unavailable",
  "reason": "paced:tageskontingent",
  "retryable": true
}

Idempotenz ​

Sendet ihr denselben Idempotency-Key für denselben Mandanten erneut (z. B. nach einem Netzwerk-Timeout eurer Anwendung), liefert Dispatch dieselbe ursprüngliche Nachricht zurück, replay: true — es wird nichts doppelt versendet.

Validierungsfehler ​

422 im Standard-Laravel-Format:

json
{
  "message": "Die angegebenen Daten sind ungültig.",
  "errors": {
    "recipient": ["Das Feld recipient ist erforderlich."]
  }
}

Status abfragen — GET /v1/message/{id} ​

json
{
  "message_id": 483920,
  "status": "delivered",
  "accepted_at": "2026-09-21T09:00:00+00:00",
  "sent_at": "2026-09-21T09:00:04+00:00",
  "delivered_at": "2026-09-21T09:00:07+00:00",
  "bounced_at": null,
  "complained_at": null,
  "bounce_code": null,
  "bounce_category": null,
  "bounce_diagnostic": null
}

Gehört die id einer fremden Nachricht (oder existiert nicht), antwortet Dispatch bewusst 404 statt 403 — so lässt sich von außen nicht einmal feststellen, ob eine fremde Nachrichten-ID existiert.

Weitere Endpunkte ​

  • POST /v1/send/batch — bis zu 100 Nachrichten je Aufruf (siehe unten).
  • GET /v1/quota — Kontingent/Warmup je Sende-Domain (Kapitel 6).
  • GET /v1/sending-identities/{id} — Absender einer eigenen Versandidentität (from_name, from_email, reply_to). Der Name im Postfach kommt immer aus der Identität; damit prüft ihr, ob er zu eurem eigenen Absender passt.
  • POST /v1/warmup/forecast — Prognose der verfügbaren Kapazität.
  • GET /v1/stats/campaign/{id} / GET /v1/stats/domain/{sendingDomain} — aggregierte Zustellstatistik.
  • POST /v1/suppressions, DELETE /v1/suppressions, POST /v1/suppression/check — Suppression verwalten/prüfen (Kapitel 7).
  • POST /v1/unsubscribe/{token} — One-Click-Abmeldung (Kapitel 7).

Viele Nachrichten auf einmal — POST /v1/send/batch ​

Für Newsletter und andere Massensendungen: bis zu 100 Nachrichten und 10 MB je Aufruf. Jede Nachricht hat dieselben Felder wie bei POST /v1/send, plus ein eigenes idempotency_key im Body (statt des Headers). Was für alle gleich ist, steht einmal in defaults:

json
{
  "defaults": {
    "sending_identity_id": 12,
    "external_campaign_reference": "newsletter-2026-10",
    "campaign_name": "Newsletter Oktober"
  },
  "messages": [
    {
      "idempotency_key": "nl-2026-10-000001",
      "recipient": "kunde@beispiel-mandant.test",
      "subject": "Herbstprogramm",
      "body_html": "<p>Hallo Erika, …</p>"
    }
  ]
}

Antwort 200 mit einem Ergebnis je Nachricht, in derselben Reihenfolge:

json
{
  "results": [
    {
      "index": 0,
      "idempotency_key": "nl-2026-10-000001",
      "status": "accepted",
      "message_id": 483921,
      "campaign_id": 68,
      "replay": false
    }
  ],
  "summary": { "accepted": 1 }
}

status je Nachricht: accepted, held, failed wie bei POST /v1/send; rejected heißt, diese eine Nachricht war ungültig (error.errors nennt die Felder); deferred heißt, es wurde nichts angelegt, übergebt sie später mit demselben idempotency_key erneut. Ist der Aufruf größer als 10 MB, antwortet Dispatch 413 (dispatch_batch_too_large), ohne etwas anzulegen.

Gegendruck: 429 bei vollem Rückstand ​

Dispatch hält je Sende-Domain höchstens 3 Tageslimits an wartenden Nachrichten zurück (bei 20.000/Tag also 60.000). Ist diese Grenze erreicht, nimmt Dispatch keine weiteren Nachrichten an, die warten müssten:

  • POST /v1/send antwortet 429 mit Retry-After (Sekunden bis zum nächsten Kontingent-Tag, Mitternacht Europe/Berlin):

    json
    {
      "code": "dispatch_backlog_full",
      "retryable": true,
      "retry_after_seconds": 39600
    }
  • POST /v1/send/batch antwortet als Ganzes 429, wenn die Grenze schon vor dem Aufruf erreicht war. Wird sie erst während des Aufrufs erreicht, kommen die übrigen Nachrichten als deferred zurück.

In beiden Fällen wird nichts angelegt. Wiederholt die Übergabe nach Retry-After mit denselben Idempotency-Keys, oder stellt die Empfänger auf anderem Weg zu. Nachrichten, die sofort Kontingent haben, und Steuerungsmails (z. B. Double-Opt-in) sind davon nicht betroffen.

Ablauf: Eine Nachricht, die 3 Tage nach der Annahme noch wartet, wird nicht mehr zugestellt (failed, expired:max-hold-days). Für Termine und Angebote ist ein späterer Versand meist schlimmer als keiner. Einen Webhook dafür gibt es nicht; den Status zeigen GET /v1/message/{id} und der Kundenbereich.

Roh-Listen / Kaltkontakt (Compliance-Sende-Gate) ​

Ist ein Stream als Roh-Liste eingestuft (purpose=raw, von Host Universe gesetzt — für Zielgruppen ohne bestehende Zustellhistorie, z. B. einen Erstkontakt), gelten zusätzlich drei Regeln:

  1. Nur Einladungen. POST /v1/send an eine Roh-Liste akzeptiert ausschließlich campaign_class: "invite". Alles andere liefert 422.
  2. Betreiber-Freigabe zuerst. Der Stream muss von Host Universe einmalig freigegeben sein, bevor überhaupt eine Nachricht angenommen wird — sonst 422, auch bei korrekt markierter Einladung. Das ist eine bewusste Wartezeit: meldet euch bei eurem Ansprechpartner, um einen neuen Roh-Listen-Stream freischalten zu lassen.
  3. Pflicht-Textbausteine. Host Universe kann je Stream Textbausteine hinterlegen (typischerweise Impressum- und Abmeldehinweis), die im Nachrichtentext vorkommen müssen. Fehlt einer, kommt 422 mit den fehlenden Bausteinen im Klartext.

Was Dispatch nicht prüft: ob eine einzelne Empfängeradresse tatsächlich eine wirksame Einwilligung oder ein berechtigtes Interesse für den Kaltkontakt hat. Diese fachliche Einstufung bleibt bei euch als Absender — Dispatch erzwingt nur den technischen Mindeststandard.

Ergebnis ​

Ihr könnt Nachrichten senden, Idempotenz und Backpressure korrekt behandeln und den Zustand jeder Nachricht zuverlässig abfragen. Für ausgehende Webhooks weiter mit Kapitel 10, für Kontingent/Warmup mit Kapitel 6.

Die vollständige, maschinenlesbare Referenz (alle Felder, alle Schemata) steht unter dispatch.host-universe.com/docs/api.

Host Universe Dispatch