Nachrichten der API

Sende E-Mails, SMS und WhatsApp-Nachrichten als deine Organisation, verwende einen Idempotenzschlüssel für Wiederholungen innerhalb seiner dokumentierten Aufbewahrungsgrenzen und sieh das Ergebnis jeder Nachricht einzeln oder im Bericht.

Ein erfolgreicher Versand antwortet normalerweise mit 202 Accepted, Kennung und Status. Annahme ist keine Zustellung durch den Anbieter: Der Versand erfordert aktivierte ausgehende Zustellung, laufende Kanal-Consumer und die Anbieterkonfiguration des Kanals. Eine Zustellzeit ist nicht garantiert. Bei deaktivierter ausgehender Zustellung bedeutet eine angenommene Anfrage nicht, dass eine Nachricht gesendet wird. Ihre Kennung, msg_ gefolgt von 32 Hexadezimalzeichen, dient zum Nachsehen des Ergebnisses hier oder in einem Webhook.

202 Angenommen

{
  "status": "success",
  "data": { "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60", "status": "queued" },
  "errors": null
}

POST/external/v1/messages/email

Eine E-Mail senden

Eine E-Mail geht von einer verifizierten Absenderidentität deiner Organisation aus, mit eigenem HTML oder dem einer deiner E-Mail-Vorlagen.

  • Name
    to
    Typ
    string[]
    Beschreibung

    Optional, wenn cc oder bcc Empfänger enthält. Gib insgesamt 1 bis 50 Adresseinträge über to, cc und bcc an; jede einzelne Liste darf fehlen oder leer sein. Eine leere Gesamtmenge wird bei to abgelehnt.

  • Name
    cc
    Typ
    string[]
    Beschreibung

    Adressen für den Cc-Header. Sie erhalten denselben E-Mail-Inhalt wie die übrigen Empfänger.

  • Name
    bcc
    Typ
    string[]
    Beschreibung

    Adressen für die Bcc-Zustellliste. Bcc wird in den Nachrichtendatensätzen und Webhooks des Absenders nicht verborgen.

  • Name
    from
    Typ
    string
    Beschreibung

    Die Adresse einer verifizierten Identität oder eine beliebige Adresse einer verifizierten Domainidentität. Ohne sie ist der verifizierte Primary-Absender der Organisation erforderlich; eine andere verifizierte Identität ersetzt ihn nicht. Sendet Oblic für eine Identität, ist die sichtbare From-Adresse ein Alias auf Oblics konfigurierter Versanddomain statt der Adresse der Identität.

  • Name
    fromName
    Typ
    string
    Beschreibung

    Der Absendername, höchstens 255 Zeichen, ohne <, >, " oder Zeilenumbruch. Ohne ihn gilt der Anzeigename der Identität. Oblic ergänzt via Oblic, wenn es für die Identität sendet.

  • Name
    replyTo
    Typ
    string
    Beschreibung

    Die Adresse für Antworten. Sendet Oblic für eine Identität, gehen Antworten an deren ursprüngliche verifizierte Adresse, sofern replyTo sie nicht überschreibt.

  • Name
    subject
    Typ
    string
    Beschreibung

    Höchstens 1,023 Zeichen. Mit html erforderlich. Mit templateId gilt der Betreff der Vorlage, wenn du keinen angibst.

  • Name
    html
    Typ
    string
    Beschreibung

    Das HTML der E-Mail, genau wie angegeben gesendet. Gib html oder templateId an, niemals beides.

  • Name
    text
    Typ
    string
    Beschreibung

    Eine Klartextversion neben dem HTML für Mailprogramme, die Text anzeigen. Mit templateId werden ihre {{name}}-Platzhalter aus variables unverändert und ohne Escaping gefüllt.

  • Name
    templateId
    Typ
    string
    Beschreibung

    Die Kennung der zu sendenden E-Mail-Vorlage, 18 ASCII-Buchstaben und Ziffern.

  • Name
    variables
    Typ
    object
    Beschreibung

    Mit templateId ein Wert für jeden {{name}}-Platzhalter der Vorlage: höchstens 100, jeder eine Zeichenfolge mit höchstens 10,000 Zeichen. Groß- und Kleinschreibung der Namen ist unerheblich. Im HTML werden Werte HTML-escaped, sodass als <b> übergebener Text als <b> erscheint.

  • Name
    attachments
    Typ
    object[]
    Beschreibung

    Höchstens 10 Dateien, jede als {"fileName": …, "content": …} mit den Dateibytes in base64, zusammen höchstens 10 MB. Dateien wie ZIP-Archive, CSV und ICS können angenommen werden; von SES verweigerte Erweiterungen und erkannte ausführbare Inhalte werden abgelehnt. Kampagnen-Uploads behalten ihre eigene Zulassungsliste.

  • Name
    metadata
    Typ
    object
    Beschreibung

    Deine Zeichenfolgen nach Schlüssel, etwa Auftrags- oder Mandantenkennung, werden mit der Nachricht und jedem ihrer Webhooks zurückgegeben und niemals an Empfänger gesendet. Siehe Metadaten.

Alle drei Empfängerlisten erhalten denselben Inhalt. To- und Cc-Adressen sind in den Empfänger-Headern sichtbar; Bcc-Adressen erscheinen weiterhin in der Nachrichtenliste und den Webhooks des Absenders. Das Ledger speichert keine To/Cc/Bcc-Rolle pro Empfänger.

Diese Listen erfordern kompatible Versionen der API und des Functions-Senders. Aktiviere den aktualisierten Sender vor oder zusammen mit der API. Die Prüfung von Anhängen ist eine separat konfigurierte Kontrolle; die Annahme beweist weder einen erfolgten Scan noch Schadsoftwarefreiheit.

Eine E-Mail mit eigenem HTML

curl -X POST https://api.oblic.app/external/v1/messages/email \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-1042-confirmation' \
  -d '{
    "from": "orders@example.com",
    "fromName": "Example Store",
    "to": ["asha@example.org"],
    "subject": "Your order is confirmed",
    "html": "<p>Thank you for your order.</p>"
  }'

Eine E-Mail aus einer Vorlage

curl -X POST https://api.oblic.app/external/v1/messages/email \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": ["asha@example.org"],
    "templateId": "TEM000R7ZM4Q2VXH00",
    "text": "Hi {{first_name}}, your order {{order_id}} is confirmed.",
    "variables": { "first_name": "Asha", "order_id": "1042" }
  }'

Abgemeldete Empfänger oder Adressen auf der Unterdrückungsliste werden übersprungen: Für sie ist die Nachricht skipped; ein email.suppressed-Webhook nennt den Grund.

AblehnungcdWann
400das Feld, etwa TO[0]Ein Feld fehlt oder ist ungültig; eine leere oder zu große kombinierte Empfängermenge wird bei to abgelehnt
400INVALID_REQUESTWeder oder beide von html und templateId, variables ohne Vorlage oder kein Betreff
400INVALID_VARIABLESEin Platzhalter hat keinen Wert, ein Name wird mit unterschiedlicher Schreibweise doppelt angegeben oder der gefüllte Betreff ist zu lang
400INVALID FILEEin Anhang ist zu groß oder hat einen nicht erlaubten Typ
403EMAIL_SUSPENDEDDer E-Mail-Versand des Kontos ist wegen Bounces oder Spam-Beschwerden gesperrt, bis Oblics Support die Sperre aufhebt
413MESSAGE_TOO_LARGEDie E-Mail ist zu groß für die Warteschlange
422UNVERIFIED_SENDERfrom gehört keiner verifizierten Identität; die Antwort nennt die verifizierten
422TEMPLATE_NOT_FOUNDEs gibt keine E-Mail-Vorlage mit dieser Kennung
422TEMPLATE_HAS_MENTIONSDie Vorlage enthält Dashboard-Erwähnungen wie @unsubscribe, die nur Kampagnen und Automatisierungen füllen
429RATE_LIMITEDÜber dem stündlichen Kontolimit (standardmäßig 5,000 Empfänger) oder dem Limit für eine Adresse (standardmäßig 10 pro Stunde); jeder Versand zählt die kanonischen unterschiedlichen Empfänger aus allen drei Listen, sodass eine wiederholte Adresse in diesem Versand einmal zählt. Retry-After nennt den Zeitpunkt
429QUOTA_EXCEEDEDDas Monatskontingent des Kontos ist überschritten (standardmäßig 100,000 Nachrichten); Retry-After sagt, wann erneut versucht werden kann

Bei aktiviertem Reputations-Worker prüfen dessen konfigurierbare Standardwerte die eigenen E-Mails jedes Kontos der letzten 7 Tage, sobald an 500 Empfänger gesendet wurde: Ab 2% Bounces oder 0.05% Spam-Beschwerden werden die Eigentümer gewarnt, ab 4% oder 0.08% wird der E-Mail-Versand gesperrt, bis Oblics Support ihn freigibt. Mit diesen Standardwerten werden Beschwerden erst ab 1,251 Empfängern bewertet, sodass eine einzelne Beschwerde kein Konto sperrt. Nur harte Bounces zählen, jeder Empfänger einmal. Ein pausierter oder deaktivierter Worker führt diese regelmäßige Prüfung nicht aus. Während einer Sperre wird eine E-Mail mit EMAIL_SUSPENDED abgelehnt; eine bereits angenommene, noch nicht gesendete E-Mail schlägt mit einem email.failed-Ereignis fehl, dessen failureCode EMAIL_SUSPENDED ist.


POST/external/v1/messages/sms

Eine SMS senden

Eine SMS geht an eine indische Mobilnummer und muss einer für dein Konto zugelassenen DLT-Vorlage entsprechen: unveränderter fester Text, alle Variablen gefüllt. Gib den Text an, damit Oblic die Vorlage findet, oder ihre DLT-Kennung und Variablen.

  • Name
    to
    Typ
    string
    Beschreibung

    Erforderlich: +91 und zehn Ziffern, die erste zwischen 6 und 9. Leerzeichen und Bindestriche werden ignoriert.

  • Name
    text
    Typ
    string
    Beschreibung

    Die Nachricht mit höchstens 2,000 Zeichen als ausgefüllte Vorlage: Jede Variable umfasst 1 bis 30 Zeichen in einer Zeile. Text mit Zeichen außerhalb einfachen ASCII, etwa é oder ₹, passt nur zu Unicode-Vorlagen.

  • Name
    templateId
    Typ
    string
    Beschreibung

    Statt text: die DLT-Kennung der Vorlage mit höchstens 32 Ziffern.

  • Name
    variables
    Typ
    string[]
    Beschreibung

    Mit templateId ein Wert je Vorlagenvariable in Reihenfolge, höchstens 30 Werte. Jeder hat 1 bis 30 Zeichen in einer Zeile und einfaches ASCII, außer bei Unicode-Vorlagen.

  • Name
    senderId
    Typ
    string
    Beschreibung

    Der DLT-Absenderheader mit höchstens 11 Zeichen, der zur Vorlage gehören muss. Ohne ihn wird der Standardheader des Kontos bevorzugt.

  • Name
    purpose
    Typ
    string
    Beschreibung

    otp, transactional (Standard) oder promotional. Werbenachrichten passen nur zu Werbevorlagen, andere nur zu nicht werblichen Vorlagen.

  • Name
    unicode
    Typ
    boolean
    Beschreibung

    true, um nur Unicode-Vorlagen zu berücksichtigen.

  • Name
    metadata
    Typ
    object
    Beschreibung

    Deine Zeichenfolgen nach Schlüssel, etwa Auftrags- oder Mandantenkennung, werden mit der Nachricht und jedem ihrer Webhooks zurückgegeben und niemals an Empfänger gesendet. Siehe Metadaten.

Eine SMS

curl -X POST https://api.oblic.app/external/v1/messages/sms \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: login-7731' \
  -d '{
    "to": "+919812345678",
    "text": "Your Example code is 482913. It is valid for 10 minutes.",
    "purpose": "otp"
  }'

Ein Segment fasst höchstens 160 GSM-7-Einheiten; Erweiterungszeichen wie ^ zählen doppelt. Eine Unicode-SMS fasst stattdessen höchstens 70 UTF-16-Codeeinheiten: Ein Zeichen außerhalb der mehrsprachigen Basisebene benötigt zwei. Längere Nachrichten nutzen Segmente mit 153 GSM-7-Einheiten oder 67 UTF-16-Codeeinheiten. Werbe-SMS gehen nur von einschließlich 10:00 bis ausschließlich 21:00 indischer Zeit. Anmeldecodes, Transaktions- und Service-SMS werden wegen eines leeren Wallets nicht abgelehnt.

AblehnungcdWann
400INVALID_NUMBERto ist keine indische Mobilnummer
400INVALID_REQUESTWeder oder beide von text und templateId
400INVALID_VARIABLESDie Variablen passen nicht zur Vorlage
402INSUFFICIENT_BALANCEEine Werbe-SMS bei leerem zahlenden Wallet des Kontos
422TEMPLATE_NOT_REGISTEREDDer Text oder templateId passt zu keiner erlaubten Vorlage des Kontos oder zu keiner unter senderId
422SENDER_NOT_ALLOWEDsenderId ist kein Header einer für das Konto erlaubten Vorlage
422MESSAGE_TYPE_NOT_ENABLEDOblic sendet diesen Vorlagentyp nicht: Erlaubt sind die messageTypes des Kontos, standardmäßig nur service_implicit
422URL_NOT_WHITELISTEDEine Variable enthält einen Link, dessen Domain auf DLT nicht freigegeben ist
422OUTSIDE_PROMOTIONAL_HOURSEine Werbe-SMS außerhalb von 10:00 bis 21:00 indischer Zeit; Retry-After nennt den nächsten Versuch
429RATE_LIMITEDDas Stundenlimit des Kontos (standardmäßig 1,000 Nachrichten) oder einer Nummer (standardmäßig 10 pro Stunde) ist überschritten; Retry-After nennt den nächsten Versuch
429QUOTA_EXCEEDEDDas monatliche Segmentkontingent des Kontos (standardmäßig 10,000) ist überschritten; Retry-After nennt den nächsten Versuch
503SMS_UNAVAILABLEDie SMS konnte gerade nicht eingereiht werden; wiederhole mit demselben Idempotency-Key, oder SMS ist auf diesem Oblic nicht eingerichtet

GET /external/v1/sms/account zeigt Kontolimits, die von Oblic gesendeten Vorlagentypen und den Verbrauch dieses Monats.


POST/external/v1/messages/whatsapp

Eine WhatsApp-Nachricht senden

Eine WhatsApp-Nachricht geht von der verbundenen Nummer deines Kontos aus: als genehmigte Vorlage oder eigene Antwort innerhalb von 24 Stunden nach der letzten Nachricht der Person.

  • Name
    to
    Typ
    string
    Beschreibung

    Erforderlich: die Nummer im internationalen Format, etwa +919812345678.

  • Name
    template
    Typ
    string
    Beschreibung

    Der Name einer deiner WhatsApp-Vorlagen wie angelegt. Gib template oder text an, niemals beides.

  • Name
    language
    Typ
    string
    Beschreibung

    Die Sprache der Vorlage, etwa en oder hi; standardmäßig en.

  • Name
    variables
    Typ
    string[]
    Beschreibung

    Die Werte für {{1}}, {{2}} usw. der Vorlage in Reihenfolge: höchstens 30 mit jeweils höchstens 1,024 Zeichen.

  • Name
    headerVariables
    Typ
    string[]
    Beschreibung

    Die Werte der Variablen im Textheader der Vorlage in Reihenfolge: höchstens 5 mit jeweils höchstens 1,024 Zeichen.

  • Name
    headerMediaUrl
    Typ
    string
    Beschreibung

    Der https-Link des Bilds, Videos oder Dokuments im Vorlagenheader, höchstens 2,048 Zeichen. Ohne ihn wird das Medium verwendet, mit dem die Vorlage genehmigt wurde.

  • Name
    text
    Typ
    string
    Beschreibung

    Eine eigene Antwort mit höchstens 4,096 Zeichen, nur innerhalb von 24 Stunden nach der letzten Nachricht der Person an deine Nummer.

  • Name
    metadata
    Typ
    object
    Beschreibung

    Deine Zeichenfolgen nach Schlüssel, etwa Auftrags- oder Mandantenkennung, werden mit der Nachricht und jedem ihrer Webhooks zurückgegeben und niemals an Empfänger gesendet. Siehe Metadaten.

Eine WhatsApp-Vorlage

curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+919812345678",
    "template": "order_shipped",
    "language": "en",
    "variables": ["Asha", "1042"]
  }'

Der Vorlagenheader wird wie der Nachrichtentext gefüllt. headerVariables füllt Textheadervariablen; headerMediaUrl liefert Bild, Video oder Dokument eines Medienheaders, andernfalls dessen genehmigtes Medium. Eine Vorlage, die von der API nicht sendbare Elemente braucht, einen Standortheader, einen Button mit eigenem Wert oder eine benannte Variable wie {{first_name}}, wird vor Versand oder Belastung abgelehnt.

Eine Vorlage mit Bildkopf

curl -X POST https://api.oblic.app/external/v1/messages/whatsapp \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+919812345678",
    "template": "diwali_sale",
    "headerMediaUrl": "https://cdn.example.com/diwali.jpg",
    "variables": ["20%"]
  }'

GET /external/v1/whatsapp/recipients/{number} zeigt, ob eine Nummer Marketing abgelehnt hat und bis wann eine eigene Antwort zulässig ist.

AblehnungcdWann
400INVALID_REQUESTWeder oder beide von template und text, oder headerVariables oder headerMediaUrl mit text
402INSUFFICIENT_BALANCEEine Marketingvorlage bei leerem zahlenden Wallet des Kontos
422INVALID_NUMBERto ist keine Nummer im internationalen Format
422WHATSAPP_NOT_CONNECTEDDas Konto hat keine verbundene WhatsApp-Nummer
422TEMPLATE_NOT_FOUNDDas Konto hat keine Vorlage dieses Namens in dieser Sprache
422TEMPLATE_NOT_APPROVEDMeta hat die Vorlage nicht genehmigt
422INVALID_VARIABLESDie Variablenzahl passt nicht zum Nachrichtentext oder Textheader, oder headerVariables wird bei einem Medienheader bzw. headerMediaUrl bei einem anderen Header verwendet
422MEDIA_REQUIREDDer Header ist ein Bild, Video oder Dokument und headerMediaUrl ist kein https-Link, oder das ohne ihn verwendete genehmigte Medium ist keiner
422TEMPLATE_NOT_SENDABLEDie Vorlage braucht ein nicht sendbares Element: Standortheader, Button mit eigenem Wert oder benannte Variable
422RECIPIENT_OPTED_OUTEine Marketingvorlage an eine Nummer, die sich abgemeldet hat
422OUTSIDE_SESSION_WINDOWEine eigene Antwort mehr als 24 Stunden nach der letzten Nachricht der Person

Einen Versand wiederholen

Sende bei jedem Versand einen selbst gewählten Idempotency-Key-Header mit 1 bis 255 Zeichen, etwa deine Auftrags- oder Ereigniskennung. Bei Timeout oder unklarer Annahme wiederhole mit demselben Schlüssel und Inhalt. Deduplizierung hängt vom gespeicherten Schlüsselzustand ab, nicht von einer dauerhaften Garantie gegen jede Wiederholung:

  • Derselbe Versand erneut antwortet 202 mit der ersten Nachrichtenkennung, ohne doppelt zu senden.
  • Derselbe Schlüssel mit anderer Nachricht, einschließlich ihrer metadata, wird mit 409 IDEMPOTENCY_CONFLICT abgelehnt; nichts wird eingereiht.
  • Gültigkeitsdauer eines Schlüssels: Der Schlüsselzustand von E-Mail und WhatsApp liegt 24 Stunden in Redis; Cacheverlust oder Ablauf entfernt diese Deduplizierung, danach kann derselbe Schlüssel erneut senden. Ein SMS-Schlüssel hat in seiner gespeicherten Nachrichtenzeile keinen zeitlichen Ablauf; eine spätere SMS benötigt einen eigenen Schlüssel. Diese Grenzen garantieren keine Zustellung.
  • Schlüssel gehören deiner Organisation, je ein Satz pro Kanal, sodass derselbe Schlüssel für E-Mail und SMS dienen kann. Unter X-Oblic-On-Behalf-Of gehören sie dem Unterkonto.
  • Ein neuer Versuch wird erneut geprüft, bevor er zugeordnet wird: Eine E-Mail mit nicht mehr verifiziertem Absender oder eine WhatsApp-Antwort nach Ablauf der 24 Stunden wird abgelehnt statt mit der ersten Kennung beantwortet.

Ein leerer oder länger als 255 Zeichen langer Schlüssel ergibt 400 INVALID_IDEMPOTENCY_KEY.

Bei E-Mails gehören nicht leere Listen cc und bcc zum Idempotenz-Hash, auch wenn ihre Adressen ebenfalls in to stehen. Fehlende oder leere Listen ändern die Hash-Struktur für reine To-Anfragen nicht; die oben genannten Grenzen für gespeicherte Schlüssel und Berechtigung gelten weiterhin.


Metadaten

Gib jedem Versand metadata, deine eigenen Zeichenfolgen nach Schlüssel, um die Nachricht deinen Vorgängen zuzuordnen: Auftrag, Mandant oder Kampagne. Oblic speichert Metadaten und liefert sie in Nachrichtenantworten und Webhooks, deutet sie aber nicht für den Versand und leitet sie nicht an Empfänger oder Anbieter weiter. Geheimnisse oder sensible Werte werden nicht geschwärzt: Prüfe den Inhalt; ein erlaubter Schlüsselname ist kein Datenschutzfilter.

Eine SMS mit Metadaten

{
  "to": "+919876543210",
  "text": "Your order 1042 has shipped.",
  "metadata": { "orderId": "1042", "tenant": "acme" }
}
  • Höchstens 20 Schlüssel, je 1 bis 40 ASCII-Buchstaben und Ziffern, _, . oder -, jeder Wert eine Zeichenfolge mit höchstens 500 Zeichen. Eine Zahl oder true bleibt wie geschrieben als Zeichenfolge "1042" oder "true"; null oder ein Objekt wird mit 400 ohne Einreihen abgelehnt.
  • Sie kommen zurück unter Eine Nachricht abrufen, in jedem Eintrag von Nachrichten auflisten und als data.metadata in jedem Webhook der Nachricht: {}, wenn keine angegeben wurden.
  • Teil der Nachricht: Derselbe Idempotency-Key mit anderen Metadaten ist eine andere Nachricht, 409 IDEMPOTENCY_CONFLICT.

GET/external/v1/messages

Nachrichten auflisten

Über die API gesendete Nachrichten, neueste zuerst, je ein Eintrag pro Empfänger: Eine E-Mail an drei Adressen hat drei Einträge mit derselben id.

  • Name
    channel
    Typ
    string
    Beschreibung

    email, sms oder whatsapp; für mehrere den Parameter wiederholen.

  • Name
    status
    Typ
    string
    Beschreibung

    queued, sent, delivered, read, bounced, skipped oder failed; für mehrere den Parameter wiederholen.

  • Name
    since
    Typ
    string
    Beschreibung

    Der früheste Anforderungszeitpunkt einschließlich, in ISO 8601 mit Z oder explizitem UTC-Offset, etwa 2026-10-01T00:00:00Z. Eine lokale Uhrzeit ohne Offset ist kein eindeutiger Zeitpunkt.

  • Name
    until
    Typ
    string
    Beschreibung

    Der späteste Anforderungszeitpunkt ausschließlich, ebenfalls mit Z oder explizitem UTC-Offset.

  • Name
    limit
    Typ
    integer
    Beschreibung

    Die Anzahl, von 1 bis 100; standardmäßig 25.

  • Name
    cursor
    Typ
    string
    Beschreibung

    Das next der letzten Seite, um die folgende zu lesen. Siehe Seitennavigation.

Diese Woche übersprungene E-Mails

curl -G https://api.oblic.app/external/v1/messages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d channel=email \
  -d status=skipped \
  -d since=2026-10-19T00:00:00Z

Antwort

{
  "status": "success",
  "data": {
    "messages": [
      {
        "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
        "channel": "email",
        "to": "ravi@example.org",
        "status": "skipped",
        "reason": "unsubscribed",
        "requestedAt": "2026-10-20T08:15:02.120Z",
        "sentAt": null,
        "deliveredAt": null,
        "readAt": null,
        "failedAt": null,
        "openedAt": null,
        "clickedAt": null,
        "metadata": { "orderId": "1042" }
      }
    ],
    "next": null
  },
  "errors": null
}
  • status nutzt eine gemeinsame Menge für alle Kanäle: queued (noch nicht gesendet), sent (vom Anbieter angenommen), delivered, read, bounced, skipped (nicht gesendet, etwa an abgemeldete oder unterdrückte Adressen) und failed. reason nennt den Grund, etwa unsubscribed oder suppressed bei übersprungenen Nachrichten.
  • to ist die E-Mail-Adresse, die SMS-Nummer mit +91 oder die Ziffern der WhatsApp-Nummer ohne +.
  • Die Zeitpunkte zeigen das jeweilige Ereignis oder null; openedAt und clickedAt betreffen E-Mails.
  • metadata enthält die mitgesendeten Metadaten oder {}.

GET/external/v1/messages/{messageId}

Eine Nachricht abrufen

Eine Nachricht und ihr Ergebnis anhand der beim Versand erhaltenen Kennung. SMS und WhatsApp haben ähnliche Formen, SMS mit segments, WhatsApp mit readAt; E-Mail hat eine eigene Form mit einem Eintrag je Empfänger, sobald dessen Ereignisse eintreffen.

Eine SMS

{
  "status": "success",
  "data": {
    "id": "msg_9a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "channel": "sms",
    "status": "delivered",
    "segments": 1,
    "sentAt": "2026-10-20T08:15:03.410Z",
    "deliveredAt": "2026-10-20T08:15:06.902Z",
    "failedAt": null,
    "failureCode": null,
    "metadata": { "orderId": "1042" }
  },
  "errors": null
}

Eine E-Mail

{
  "status": "success",
  "data": {
    "id": "msg_4f9c2a1e8b7d4c3f9e0a1b2c3d4e5f60",
    "status": "sent",
    "recipients": [
      {
        "email": "asha@example.org",
        "deliveredAt": "2026-10-20T08:16:11Z",
        "openedAt": "2026-10-20T09:02:40Z",
        "bouncedAt": null,
        "complainedAt": null,
        "delayedAt": null
      }
    ],
    "metadata": {}
  },
  "errors": null
}
  • Der status einer SMS ist queued, sent, delivered, undelivered oder failed.
  • Der einer WhatsApp-Nachricht ist queued, sent, delivered, read oder failed, mit readAt. Ihr failureCode stammt von Meta, etwa meta:131026.
  • Der einer E-Mail ist bis zum Versand queued, danach sent, bei teilweise übersprungenen Empfängern partially_suppressed, bei allen suppressed oder bei Versandfehlern failed. Die Empfängerzeitpunkte stammen aus Anbieterereignissen; recipients bleibt bis zum ersten leer.
  • metadata enthält die beim Versand angegebenen Werte oder {}: siehe Metadaten.

Eine nicht vorhandene oder fremde Nachricht ergibt 404 MESSAGE_NOT_FOUND. Eine nie gesendete E-Mail ist hier nach 24 Stunden nicht mehr auffindbar; die Liste zeigt sie weiterhin.


GET/external/v1/reports/summary

Berichtsübersicht

Das Ergebnis der in einem Zeitraum angeforderten Nachrichten, gezählt nach Kanal und Status, dazu geöffnete, angeklickte oder als Spam gemeldete E-Mails.

  • Name
    from
    Typ
    string
    Beschreibung

    Der Zeitraumstart einschließlich, in ISO 8601 mit Z oder explizitem UTC-Offset; standardmäßig 30 Tage vor to.

  • Name
    to
    Typ
    string
    Beschreibung

    Das Zeitraumende ausschließlich, ebenfalls mit Z oder explizitem UTC-Offset; standardmäßig jetzt. Es muss nach from und höchstens 92 Tage später liegen.

Antwort

{
  "status": "success",
  "data": {
    "from": "2026-09-24T00:00:00Z",
    "to": "2026-10-24T00:00:00Z",
    "all": {
      "messages": 1250,
      "statuses": { "queued": 4, "sent": 96, "delivered": 1075, "read": 30, "bounced": 12, "skipped": 18, "failed": 15 },
      "opened": 410,
      "clicked": 96,
      "complained": 1
    },
    "channels": {
      "email": { "messages": 800, "statuses": { "queued": 2, "sent": 40, "delivered": 728, "read": 0, "bounced": 12, "skipped": 18, "failed": 0 }, "opened": 410, "clicked": 96, "complained": 1 },
      "sms": { "messages": 300, "statuses": { "queued": 1, "sent": 36, "delivered": 253, "read": 0, "bounced": 0, "skipped": 0, "failed": 10 }, "opened": 0, "clicked": 0, "complained": 0 },
      "whatsapp": { "messages": 150, "statuses": { "queued": 1, "sent": 20, "delivered": 94, "read": 30, "bounced": 0, "skipped": 0, "failed": 5 }, "opened": 0, "clicked": 0, "complained": 0 }
    }
  },
  "errors": null
}

Jeder Kanal und jeder Status ist immer enthalten, mit denselben Begriffen wie die Liste. from gleich oder nach to, oder mehr als 92 Tage Abstand, ergibt 400 INVALID_PERIOD.

War diese Seite hilfreich?