Asynchroner Export von Nachrichtenstatistiken

exportMessagesStatistics exportiert den Nachrichtenverlauf und die Statistiken in eine CSV-Datei auf dem Server. Verwenden Sie es für große oder vollständige Kontoabrufe, die messages:list nicht verarbeiten kann.

Wann sollte der Export anstelle von messages:list verwendet werden?

Verwenden Sie messages:list für Live-, paginierte Abfragen eines begrenzten Zeitraums. Verwenden Sie exportMessagesStatistics, wenn das Ergebnis das Tiefenpaginierungslimit von messages:list (page × per_page > 100000) überschreiten würde oder wenn das Ziel eine einzelne herunterladbare Datei anstelle von paginiertem JSON ist. Der Export hat keine Begrenzung für date_range oder die Zeilenanzahl, da er das Ergebnis in eine Datei auf der Festplatte streamt, anstatt es in einer einzigen Antwort zu halten.

Wie der Exportablauf funktioniert

1. Rufen Sie export mit denselben Filtern wie messages:list auf. Die Antwort gibt sofort eine Aufgabenkennung uid zurück, bevor die Datei generiert wird.
2. Fragen Sie status mit dieser uid ab, bis STATUS_SUCCESS (oder STATUS_FAILED) gemeldet wird.
3. Rufen Sie result mit derselben uid auf, um die generierte file und eine gebrauchsfertige file_url zu erhalten.
4. Laden Sie die Datei herunter. Verwenden Sie file_url unverändert oder sehen Sie unter result nach, wie die URL aus file erstellt wird, falls sie leer zurückgegeben wurde.

Verwenden Sie lastTasks, um die letzten Exportaufgaben für eine Anwendung nachzuschlagen, und delete, um eine Aufgabe abzubrechen oder ihre Datei vorzeitig zu entfernen.

Methoden

Der Export-Lebenszyklus hat fünf Methoden sowie einen einfachen Download-Endpunkt:

Methode	Beschreibung
exportMessagesStatistics/export	Stellt einen Export in die Warteschlange und gibt eine Aufgaben-uid zurück.
exportMessagesStatistics/status	Überprüft den Aufgabenfortschritt.
exportMessagesStatistics/result	Gibt den Namen der generierten Datei zurück, sobald die Aufgabe abgeschlossen ist.
exportMessagesStatistics/lastTasks	Listet die letzten Exportaufgaben für eine Anwendung auf.
exportMessagesStatistics/delete	Bricht eine Aufgabe ab oder entfernt ihre Datei, bevor das Aufbewahrungsfenster abläuft.
Download	Lädt die generierte CSV-Datei nach Namen herunter.

export

Stellt einen Export des Nachrichtenverlaufs in die Warteschlange und gibt sofort eine Aufgabenkennung zurück.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

Header

Die Anfrage benötigt einen Server-API-Token:

Name	Erforderlich	Beschreibung
Authorization	Ja	Server-API-Token. Muss im folgenden Format bereitgestellt werden: Authorization: Api <Server Key>.

Parameter des Anfragekörpers

Der Anfragekörper akzeptiert die folgenden Felder:

Name	Erforderlich	Typ	Beschreibung
type	Ja	String	Muss “TASK_TYPE_EXPORT_MESSAGES_V2” sein.
export_messages_v2	Ja	Object	Exportparameter, unten beschrieben.
export_messages_v2.application_code	Siehe Hinweis	String	Pushwoosh-Anwendungscode. Erforderlich, wenn app_group_code nicht gesetzt ist.
export_messages_v2.app_group_code	Siehe Hinweis	String	Anwendungsgruppencode, exportiert über jede App in der Gruppe. Erforderlich, wenn application_code nicht gesetzt ist.
export_messages_v2.search	Nein	String	Freitextsuche über Nachrichtentitel und -inhalt.
export_messages_v2.filters	Nein	Object	Nachrichtenfilter, unten beschrieben. Weglassen, um den gesamten Kontoverlauf zu exportieren.
export_messages_v2.properties	Nein	Array	Spalten, die in die CSV-Datei aufgenommen werden sollen, unten beschrieben.

export_messages_v2.filters akzeptiert:

Name	Typ	Beschreibung
statuses	Array	Einzuschließende Nachrichtenstatus. Mögliche Werte ”MESSAGE_STATUS_CANCELED" "MESSAGE_STATUS_CREATING" "MESSAGE_STATUS_DONE" "MESSAGE_STATUS_FAIL" "MESSAGE_STATUS_PENDING" "MESSAGE_STATUS_PROCESSING" "MESSAGE_STATUS_WAITING”
platforms	Array	Plattformcodes (numerisch, z. B. 1 für iOS), nicht die von messages:list verwendeten Plattformnamen-Strings.
sent_date	Object	Berichtszeitraum, gefiltert nach Sendedatum: {"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}.
created_date	Object	Berichtszeitraum, gefiltert nach Erstellungsdatum der Nachricht, gleiches Format wie sent_date.
created_via	Array	Nachrichtenquelle. Mögliche Werte ”AB_TEST" "API" "AUTO_PUSH" "CP" "CSV" "CUSTOMER_JOURNEY" "EMAIL_API" "EMAIL_CP" "GEO_ZONE" "PUSH_ON_EVENT" "RSS" "SYSTEM”
segments	Array	Filtercodes, an die die Nachricht gesendet wurde.
campaigns	Array	Kampagnencodes. Im Gegensatz zu messages:list wird hier eine Liste und nicht ein einzelner Code verwendet.
message_id	String (uint64)	Eine einzelne numerische Nachrichten-ID, in Anführungszeichen. Im Gegensatz zu messages:list nimmt der Export eine ID, nicht ein Array.
message_code	String	Ein einzelner Nachrichtencode.

export_messages_v2.properties wählt aus, welche Spalten die CSV-Datei enthält.

Mögliche Werte

• "EXPORT_MESSAGE_PROPERTY_ID"
• "EXPORT_MESSAGE_PROPERTY_TIMESTAMP"
• "EXPORT_MESSAGE_PROPERTY_CONTENT"
• "EXPORT_MESSAGE_PROPERTY_TITLE"
• "EXPORT_MESSAGE_PROPERTY_CAMPAIGN_NAME"
• "EXPORT_MESSAGE_PROPERTY_APPLICATIONS"
• "EXPORT_MESSAGE_PROPERTY_STATUS"
• "EXPORT_MESSAGE_PROPERTY_PLATFORMS"
• "EXPORT_MESSAGE_PROPERTY_SOURCE"
• "EXPORT_MESSAGE_PROPERTY_FILTER"
• "EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"
• "EXPORT_MESSAGE_PROPERTY_SENT"
• "EXPORT_MESSAGE_PROPERTY_OPENED"
• "EXPORT_MESSAGE_PROPERTY_ERRORS"
• "EXPORT_MESSAGE_PROPERTY_RECIPIENTS"
• "EXPORT_MESSAGE_PROPERTY_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"
• "EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_CLICKS"
• "EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"

properties ist nicht nur ein Filter

Eine Eigenschaft, die nicht in properties aufgeführt ist, erscheint überhaupt nicht in der Datei, einschließlich der Basisspalten (ID, Sendedatum, Inhalt, Status). Wenn properties leer gelassen wird, wird eine CSV-Datei ohne Spalten erstellt. Listen Sie jede Spalte auf, die der Export enthalten soll, nicht nur die Metriken, die Sie zu einem Standardsatz hinzufügen möchten.

Beispielanfrage

{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}

200: OK

{
  "uid": "177458"
}

401: Falscher API-Zugriffstoken

{
  "error": "account not found"
}

status

Gibt den Fortschritt einer Exportaufgabe zurück.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status

Parameter des Anfragekörpers

Übergeben Sie die von export zurückgegebene Aufgabenkennung:

Name	Erforderlich	Typ	Beschreibung
uid	Ja	String (int64)	Aufgabenkennung aus der export-Antwort, z. B. "177458".

Beispielanfrage

{
  "uid": "177458"
}

200: OK

{
  "status": "STATUS_SUCCESS",
  "progress": 1
}

status ist einer von "STATUS_PENDING", "STATUS_SUCCESS" oder "STATUS_FAILED". progress ist ein Bruchteil zwischen 0 und 1; fragen Sie status ab, bis es "STATUS_SUCCESS" erreicht, bevor Sie result aufrufen.

result

Gibt den Namen der generierten Datei zurück, sobald die Aufgabe abgeschlossen ist.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result

Parameter des Anfragekörpers

Übergeben Sie dieselbe von export zurückgegebene Aufgabenkennung:

Name	Erforderlich	Typ	Beschreibung
uid	Ja	String (int64)	Aufgabenkennung aus der export-Antwort, z. B. "177458".

Beispielanfrage

{
  "uid": "177458"
}

200: OK

{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}

Der Aufruf von result, bevor status "STATUS_SUCCESS" meldet, gibt ein leeres Ergebnis zurück. file_url ist ein gebrauchsfertiger Link zum Download-Endpunkt auf dem korrekten Rechenzentrum für das Konto – verwenden Sie ihn unverändert, anstatt die URL selbst aus file zu erstellen. file_url ist leer, wenn für das Rechenzentrum des Kontos keine Basis-URL konfiguriert ist. In diesem Fall können Sie nur auf das Erstellen der URL aus file zurückgreifen, wenn sich das Konto im Standard-Rechenzentrum app.pushwoosh.com befindet – ein Konto in einem anderen Rechenzentrum oder auf einer Whitelabel-Domain hat keine Möglichkeit, den korrekten Host allein aus file abzuleiten.

lastTasks

Listet die letzten Exportaufgaben für eine Anwendung auf, die neuesten zuerst.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks

Parameter des Anfragekörpers

Jeder Parameter ist ein optionaler Filter; lassen Sie alle weg, um jede Aufgabe aufzulisten, auf die der Token Zugriff hat:

Name	Erforderlich	Typ	Beschreibung
application	Nein	String	Pushwoosh-Anwendungscode. Weglassen, um Aufgaben für alle Anwendungen aufzulisten, auf die der Token Zugriff hat.
types	Nein	Array	Auf bestimmte Aufgabentypen beschränken. Verwenden Sie [“TASK_TYPE_EXPORT_MESSAGES_V2”], um nur Nachrichtenexporte anzuzeigen.
campaign	Nein	String	Nach Kampagnencode filtern.
message_id	Nein	String (uint64)	Nach einer einzelnen numerischen Nachrichten-ID filtern, in Anführungszeichen.
message_code	Nein	String	Nach einem einzelnen Nachrichtencode filtern.
limit	Nein	Integer	Maximale Anzahl der zurückzugebenden Aufgaben.
timestamp_from	Nein	String	Nur Aufgaben zurückgeben, die nach diesem Zeitstempel (RFC 3339) erstellt wurden.

Hinweis

Aufgaben werden 30 Tage lang aufbewahrt, unabhängig davon, ob ihre Datei bereits nach dem 7-tägigen Aufbewahrungsfenster gelöscht wurde. lastTasks kann immer noch eine Aufgabe anzeigen, deren result nicht mehr zu einer herunterladbaren Datei aufgelöst wird.

Beispielanfrage

{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}

200: OK

{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv",
        "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}

delete

Löscht eine Aufgabe und ihre Datei, bevor das 7-tägige Aufbewahrungsfenster abläuft.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete

Parameter des Anfragekörpers

Übergeben Sie die von export zurückgegebene Aufgabenkennung:

Name	Erforderlich	Typ	Beschreibung
uid	Ja	String (int64)	Aufgabenkennung aus der export-Antwort, z. B. "177458".

Beispielanfrage

{
  "uid": "177458"
}

200: OK

{}

Download

Lädt die von result generierte CSV-Datei nach Namen herunter.

GET https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>

Header

Authentifizieren Sie sich auf die gleiche Weise wie bei den anderen Methoden oder verlassen Sie sich auf eine aktive Control Panel-Sitzung:

Name	Erforderlich	Beschreibung
Authorization	Ja	Server-API-Token, im gleichen Format wie die anderen exportMessagesStatistics-Methoden: Authorization: Api <Server Key> (das Api-Schema ist nicht case-sensitiv). Eine Anfrage ohne Authorization-Header und ohne angemeldete Control Panel-Sitzung erhält 401 Unauthorized.

Ersetzen Sie <file> durch den exakten file-Wert aus der result-Antwort, zum Beispiel:

https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv

Vorsicht

Das manuelle Erstellen dieser URL funktioniert nur für Konten im Standard-Rechenzentrum app.pushwoosh.com. Ein Konto in einem anderen Rechenzentrum (app.wavesend.ru für OVB, app.pushwoosh.us für IAD) oder auf einer Whitelabel-Domain benötigt einen anderen Host, und es gibt keine Möglichkeit, diesen allein aus file abzuleiten. Verwenden Sie stattdessen die file_url aus result oder lastTasks, da sie bereits auf den richtigen Host für das Konto verweist. Sehen Sie unter result nach, was zu tun ist, wenn file_url leer zurückgegeben wird.

Die Datei ist eine CSV-Datei, die die in properties ausgewählten Spalten enthält. Sie bleibt 7 Tage nach Abschluss des Exports verfügbar, dann entfernt der Bereinigungsjob sie und die URL ist nicht mehr auflösbar.

Export der Nachrichtenempfänger

Dieselben Methoden export, status, result, lastTasks, delete und download exportieren auch die einzelnen Empfänger einer Nachricht. Verwenden Sie "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS" und ein export_message_recipients-Objekt anstelle von export_messages_v2.

POST https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export

Nicht der Holdout Split der Customer Journey

Dies exportiert Empfänger, die von einer Nachricht ausgeschlossen wurden. Ein Holdout Split-Punkt in der Customer Journey ist ein anderer Mechanismus. Er schließt Benutzer vom Rest einer Journey aus, bevor eine Nachricht gesendet wird, und seine exportJourneyPointUsers-Aufgabe (dieselben Methoden export/status/result, ein anderer type) meldet die Zugehörigkeit zu Zweigen, nicht Sendeergebnisse.

Anfragefelder von export_message_recipients

Name	Erforderlich	Typ	Beschreibung
message_id	Siehe Hinweis	String (uint64)	Eine einzelne numerische Nachrichten-ID. Erforderlich, wenn campaign nicht gesetzt ist.
campaign	Siehe Hinweis	String	Ein einzelner Kampagnencode. Erforderlich, wenn message_id nicht gesetzt ist. Werden beide gesetzt, wird auf die Zeilen der Nachricht innerhalb dieser Kampagne eingeschränkt.
application	Ja	String	Anwendungscode, zu dem die Nachricht gehört.
type	Ja	String	Welche Empfänger exportiert werden sollen. Einer von "sends", "deliveries", "opens", "holdout" (siehe unten).
date_from / date_to	Nein	String (date-time)	Zeilen auf dieses Zeitfenster beschränken. Beides weglassen, um den gesamten Verlauf der Nachricht zu erhalten.

Fehlen message_id und campaign zugleich oder fehlt application, schlägt der Export mit einem Fehler fehl, der das fehlende Feld nennt. Eine message_id aus einem anderen Konto schlägt mit NotFound: message not found fehl; dies wird vor dem Export geprüft. Eine message_id oder campaign, die zu einer anderen Anwendung im selben Konto gehört, wird nicht abgelehnt. Sie trifft auf keine Zeilen, und die CSV-Datei wird nur mit einer Kopfzeile heruntergeladen.

type wählt die Empfängermenge aus:

Wert	Zurückgegebene Zeilen
"sends"	Jeder Empfänger, für den die Nachricht angenommen wurde.
"deliveries"	Empfänger aus sends, deren Zustellung vom Anbieter bestätigt wurde.
"opens"	Empfänger aus sends, die die Nachricht geöffnet haben.
"holdout"	Empfänger, die von dieser Nachricht ausgeschlossen wurden, nicht von einer anderen. An sie wurde nichts gesendet. Sowohl eine kontoweite Kontrollgruppe als auch das eigene holdout_percentage der Nachricht (siehe Messaging API v2) können diese Zeile erzeugen.

Beispielanfrage

{
  "type": "TASK_TYPE_EXPORT_MESSAGE_RECIPIENTS",
  "export_message_recipients": {
    "message_id": "22875465358",
    "application": "6D382-5ADFE",
    "type": "holdout",
    "date_from": "2026-08-01T00:00:00Z",
    "date_to": "2026-09-30T00:00:00Z"
  }
}

200: OK

{
  "uid": "29820"
}

Fragen Sie status ab und rufen Sie result genauso auf wie bei einem Export des Nachrichtenverlaufs. result gibt export_message_recipients_result anstelle von export_messages_v2_result zurück:

{
  "export_message_recipients_result": {
    "file": "Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv",
    "file_url": "https://app.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Message_22875465358_Holdout_29820-fe5d8ba468df25b7.csv"
  }
}

sends, deliveries und opens teilen sich einen Spaltensatz: hwid, user_id, platform, send_timestamp, delivery_timestamp, open_timestamp, send_error, pae, send_status. pae ist false, wenn die Plattform den Versand akzeptiert, dafür aber keinen sichtbaren Hinweis angezeigt hat; das ist derselbe Fall, den unshowable_sends in den aggregierten Statistiken zählt. holdout hat einen eigenen, kürzeren Satz: hwid, user_id, platform, holdout_timestamp.