Nachrichten senden

POST /v1/messages/send ist der eine Endpoint für alle Kanäle.

Pflichtfelder

to, channel (einer von sms, rcs, whatsapp, email, voice) und message sind erforderlich — oder übergeben Sie ein channels-Array anstelle von channel/fallback (siehe unten).

Kanal-Fallback

Geben Sie eine geordnete fallback-Liste an oder das neuere channels-Array mit dem primären Kanal an erster Stelle:

{
  "to": "+4512345678",
  "channels": ["whatsapp", "sms"],
  "message": "Ihre Bestellung wurde versandt."
}

Schlägt die WhatsApp-Zustellung fehl, versucht die Plattform es automatisch per SMS erneut — ohne separaten API-Aufruf.

Kanalspezifische Felder

• E-Mail: Setzen Sie subject und htmlmessage (oder den älteren Alias html) für den HTML-Body. message ist der Klartext-Fallback.
• WhatsApp: Übergeben Sie ein whatsapp-Objekt, z. B. { "template": "order_shipped" }, für Template-Nachrichten außerhalb des 24-Stunden-Sitzungsfensters.
• Voice: Übergeben Sie ein voice-Objekt (z. B. { "voice": "female", "language": "da-DK" }) für TTS-Parameter.
• Absender-ID: sender muss eine in Einstellungen → Absender-IDs freigegebene Absender-ID für SMS/RCS sein — es sei denn, für Ihr Konto ist allow_unverified_sender für Systemintegrationen aktiviert.

Reply-To, Absendername und eigene Header

Drei optionale E-Mail-Felder:

• reply_to — wohin Antworten gehen. Entweder eine reine Adresse (support@ihrunternehmen.de) oder die Form mit Anzeigename (Support <support@ihrunternehmen.de>); der Adressteil wird als E-Mail-Adresse validiert. Das Feld ist bewusst nicht domain-gebunden — Reply-To ist nicht der Envelope-Absender, Sie können Antworten also an jedes Postfach leiten, das Sie kontrollieren.
• from_name — der Anzeigename im From, unabhängig von der From-Adresse gesetzt.
• headers — ein Objekt aus Headername → Wert, z. B. { "X-Order-Id": "10432" }. Namen müssen [A-Za-z0-9][A-Za-z0-9-]* entsprechen.

headers ist eine Safelist, kein Passthrough. Diese Namen sind reserviert und können nicht gesetzt werden: List-Unsubscribe, List-Unsubscribe-Post, From, Sender, Return-Path, Reply-To, DKIM-Signature, Received sowie alles, was mit X-WeZend beginnt — alle ohne Beachtung der Groß- und Kleinschreibung geprüft. Sie schützen die Konformität des One-Click-Abmeldens, die E-Mail-Authentifizierung und die Envelope-Identität. Reply-To ist reserviert, weil es ein eigenes validiertes reply_to-Feld hat; ein Roh-Header würde diese Validierung umgehen.

Ein reservierter Name wird abgelehnt und nicht stillschweigend verworfen, und der Fehler benennt den betreffenden Header:

{
  "to": "kunde@example.com",
  "channel": "email",
  "subject": "Ihre Rechnung",
  "message": "Danke für Ihre Bestellung.",
  "headers": { "List-Unsubscribe": "<mailto:opt-out@example.com>" }
}

{ "error": "Header \"List-Unsubscribe\" is reserved and cannot be set" }

Alle drei Felder werden in den send_options der Nachricht gespeichert und überstehen damit die Queue.

Zeitplanung und Webhooks pro Nachricht

scheduled_at (ISO-Zeitstempel) verzögert den Versand. webhook_url empfängt Zustellstatus-Updates für genau diese Nachricht — siehe Webhooks.

Frequenzgrenzen für Marketing

Übergeben Sie eine category (z. B. "newsletter"), damit dieser Versand auf die Frequenzgrenze dieser Kategorie angerechnet wird, die kontoweit in der Sendepolicy konfiguriert wird — unabhängig von der globalen kanalübergreifenden Grenze und etwaigen Grenzen pro Kanal.

Transaktionale Sendungen

Übergeben Sie transactional: true (den Boolean oder den String "true"), um eine Sendung als transaktional zu markieren — ein Passwort-Reset, eine Rechnung, eine Opt-in-Bestätigung. Standard ist false: eine normale Sendung ist Marketing.

Transaktionale Mail ist von der Marketing-Grenze Ihres Bands ausgenommen. Über der Grenze wird sie pro Nachricht als Overage abgerechnet, statt mit quota_exceeded abgelehnt zu werden — ein kampagnenstarker Monat kann Ihre Passwort-Reset-Mails also nicht zum Stillstand bringen. Sie wird weiterhin gezählt, das Volumen bleibt im Verbrauchsreporting sichtbar, und das Flag wird auf der Nachrichtenzeile gespeichert — es übersteht die Queue und etwaige Wiederholungsversuche.

Es gibt genau einen Quota-Fall, in dem transaktionale Mail weiterhin blockiert wird: ein Free-Plan ohne hinterlegte Karte, bei dem sich die Overage nicht abrechnen lässt. region_blocked und payment_method_required sind keine Quota-Entscheidungen, transactional überschreibt sie also ebenfalls nicht.

transactional: true nimmt die Sendung zusätzlich von Frequenzgrenzen und Ruhezeiten aus.

Alle vier Felder pro Sendung — transactional, reply_to, from_name und headers — werden auch pro Eintrag in POST /v1/messages/bulk akzeptiert. Dort führt ein ungültiges reply_to oder ein reservierter Headername nur zum Fehlschlag dieses Eintrags (er wird in failed gezählt), statt den gesamten Batch abzulehnen.

Antwort

{
  "message_id": "3fa1e2c0-...",
  "status": "queued",
  "channel": "sms",
  "to": "+4512345678",
  "cost": 0.045,
  "currency": "EUR",
  "created_at": "2026-07-08T10:00:00.000Z"
}

Ein 402 bedeutet unzureichendes Guthaben oder eine fehlende Zahlungsmethode; 403 bedeutet, dass das Konto gesperrt ist, auf Aktivierung wartet oder die Absender-ID nicht freigegeben ist; 409 bedeutet, dass die empfangende Person diesen Kanal abbestellt hat.