Email API

createEmailMessage

Erstellt eine E-Mail-Nachricht.

POST https://api.pushwoosh.com/json/1.3/createEmailMessage

Parameter des Request-Body

Name	Typ	Erforderlich	Beschreibung
auth	string	Ja	API-Zugriffstoken aus dem Pushwoosh Control Panel.
application	string	Ja	Pushwoosh Application Code
notifications	array	Ja	JSON-Array mit Details zur E-Mail-Nachricht. Siehe Tabelle Benachrichtigungsparameter unten.

Benachrichtigungsparameter

Name	Typ	Erforderlich	Beschreibung
send_date	string	Ja	Legt fest, wann die E-Mail gesendet werden soll. Format: YYYY-MM-DD HH:mm oder "now".
preset	string	Ja	E-Mail-Preset-Code. Kopieren Sie diesen aus der URL-Leiste des Email Content Editor im Pushwoosh Control Panel.
subject	string oder object	Nein	Betreffzeile der E-Mail. Die E-Mail wird immer in der Sprache des Inhalts sein. Wenn subject keine passende Sprache für content enthält, bleibt der Betreff leer.
content	string oder object	Nein	Der Inhalt des E-Mail-Bodys. Kann ein String für reinen HTML-Inhalt oder ein Objekt für lokalisierte Versionen sein.
attachments	array	Nein	Die E-Mail-Anhänge. Es sind nur zwei Anhänge verfügbar. Jeder Anhang darf 1 MB nicht überschreiten (Base64-kodiert).
list_unsubscribe	string	Nein	Erlaubt das Setzen einer benutzerdefinierten URL für den „Link-Unsubscribe“-Header.
campaign	string	Nein	Kampagnencode, um die E-Mail einer bestimmten Kampagne zuzuordnen.
ignore_user_timezone	boolean	Nein	Wenn true, wird die E-Mail sofort gesendet, Zeitzonen der Benutzer werden ignoriert.
timezone	string	Nein	Sendet die E-Mail gemäß der Zeitzone des Benutzers. Beispiel: "America/New_York".
filter	string	Nein	Sendet die E-Mail an Benutzer, die einer bestimmten Filterbedingung entsprechen.
devices	array	Nein	Liste von E-Mail-Adressen (max. 1000) für gezielte E-Mails. Wenn verwendet, wird die Nachricht nur an diese Adressen gesendet. Wird ignoriert, wenn die Application Group verwendet wird.
use_auto_registration	boolean	Nein	Wenn true, werden E-Mails aus dem Parameter devices automatisch registriert.
users	array	Nein	Wenn gesetzt, wird die E-Mail-Nachricht nur an die angegebenen User IDs geliefert (registriert über /registerEmail-Aufruf). Nicht mehr als 1000 User IDs in einem Array. Wenn der Parameter „devices“ angegeben ist, wird der Parameter „users“ ignoriert.
dynamic_content_placeholders	object	Nein	Platzhalter für dynamischen Inhalt anstelle von Geräte-Tag-Werten.
conditions	array	Nein	Segmentierungsbedingungen unter Verwendung von Tags. Beispiel: [["Country", "EQ", "BR"]].
from	object	Nein	Geben Sie einen benutzerdefinierten Absendernamen und eine E-Mail-Adresse an, um den Standard in den Anwendungseigenschaften zu überschreiben.
reply-to	object	Nein	Geben Sie eine benutzerdefinierte Antwort-E-Mail an, um den Standard in den Anwendungseigenschaften zu überschreiben.
transactionId	string	Nein	Eindeutige Nachrichtenkennung, um ein erneutes Senden bei Netzwerkproblemen zu verhindern. Wird seitens Pushwoosh für 5 Minuten gespeichert.
capping_days	integer	Nein	Die Anzahl der Tage (max. 30) für das Frequency Capping pro Gerät. Hinweis: Stellen Sie sicher, dass Globales Frequency Capping im Control Panel konfiguriert ist.
capping_count	integer	Nein	Die maximale Anzahl von E-Mails, die von einer bestimmten App an ein bestimmtes Gerät innerhalb eines Zeitraums von capping_days gesendet werden können. Falls die erstellte Nachricht das Limit capping_count für ein Gerät überschreitet, wird sie nicht an dieses Gerät gesendet.
capping_exclude	boolean	Nein	Wenn auf true gesetzt, wird diese E-Mail nicht für das Capping zukünftiger E-Mails gezählt.
capping_avoid	boolean	Nein	Wenn auf true gesetzt, wird Capping auf diese spezifische E-Mail nicht angewendet.
send_rate	integer	Nein	Begrenzt, wie viele Nachrichten pro Sekunde über alle Benutzer hinweg gesendet werden können. Hilft, eine Überlastung des Backends bei hohem Versandaufkommen zu verhindern.
send_rate_avoid	boolean	Nein	Wenn auf true gesetzt, wird das Drosselungslimit nicht auf diese spezifische E-Mail angewendet.

Anfrage-Beispiel

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // erforderlich. API-Zugriffstoken aus dem Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // erforderlich. Pushwoosh Application Code.
    "notifications": [{
      "send_date": "now",               // erforderlich. YYYY-MM-DD HH:mm ODER 'now'
      "preset": "ERXXX-32XXX",          // erforderlich. Kopieren Sie den E-Mail-Preset-Code aus der URL-Leiste
                                        //           der Email Content Editor-Seite im Pushwoosh Control Panel.
      "subject": {                      // optional. Betreffzeile der E-Mail-Nachricht.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Inhalt des E-Mail-Bodys.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. E-Mail-Anhänge
        "name": "image.png",            //           "name" - Dateiname
        "content": "iVBANA...AFTkuQmwC" //           "content" - Base64-kodierter Inhalt der Datei
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Erlaubt das Setzen einer benutzerdefinierten URL für den "Link-Unsubscribe"-Header
      "campaign": "CAMPAIGN_CODE",      // optional. Um diese E-Mail-Nachricht einer bestimmten Kampagne zuzuordnen,
                                        //           fügen Sie hier einen Kampagnencode hinzu.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Geben Sie dies an, um die Nachricht gemäß der
                                        //           auf dem Gerät des Benutzers eingestellten Zeitzone zu senden.
      "filter": "FILTER_NAME",          // optional. Senden Sie die Nachricht an bestimmte Benutzer, die die Filterbedingungen erfüllen.
      "devices": [                      // optional. Geben Sie E-Mail-Adressen an, um gezielte E-Mail-Nachrichten zu senden.
        "email_address1",               //           Nicht mehr als 1000 Adressen in einem Array.
        "email_address2"                //           Wenn gesetzt, wird die Nachricht nur an die Adressen auf
      ],                                //           der Liste gesendet. Wird ignoriert, wenn die Application Group verwendet wird.
      "use_auto_registration": true,    // optional. Automatische Registrierung der im Parameter "devices" angegebenen E-Mails
      "users": [                        // optional. Wenn gesetzt, wird die E-Mail-Nachricht nur an die
        "userId1",                      //           angegebenen User IDs geliefert (registriert über /registerEmail-Aufruf).
        "userId2"                       //           Nicht mehr als 1000 User IDs in einem Array.
      ],                                //           Wenn der Parameter "devices" angegeben ist,
                                        //           wird der Parameter "users" ignoriert.
      "dynamic_content_placeholders": { // optional. Platzhalter für dynamischen Inhalt anstelle von Geräte-Tag-Werten.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentierungsbedingungen, siehe Anmerkung unten.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Geben Sie einen Absendernamen und eine Absender-E-Mail-Adresse an,
        "name": "alias from",           //           um den Standard "From name" und "From email"
        "email": "from-email@email.com" //           in den Anwendungseigenschaften zu ersetzen.
      },
      "reply-to": {                     // optional. Geben Sie eine E-Mail-Adresse an, um den
        "name": "alias reply to ",      //           Standard "Reply to" in den Anwendungseigenschaften zu ersetzen.
        "email": "reply-to@email.com"
      },
      "transactionId": "unique UUID",   // optional. Eindeutige Nachrichtenkennung, um ein erneutes Senden
                                        //           bei Netzwerkproblemen zu verhindern. Wird seitens
                                        //           Pushwoosh für 5 Minuten gespeichert.
      // Frequency Capping Parameter. Stellen Sie sicher, dass Globales Frequency Capping im Control Panel konfiguriert ist.
      "capping_days": 30,               // optional. Anzahl der Tage für Frequency Capping (max. 30 Tage)
      "capping_count": 10,              // optional. Die maximale Anzahl von E-Mails, die von einer
                                        //           bestimmten App an ein bestimmtes Gerät innerhalb eines Zeitraums
                                        //           von 'capping_days' gesendet werden können. Falls die erstellte
                                        //           Nachricht das Limit 'capping_count' für ein Gerät überschreitet,
                                        //           wird sie nicht an dieses Gerät gesendet.
      "capping_exclude": true,          // optional. Wenn auf true gesetzt, wird diese E-Mail nicht
                                        //           für das Capping zukünftiger E-Mails gezählt.
      "capping_avoid": true,            // optional. Wenn auf true gesetzt, wird Capping auf diese
                                        //           spezifische E-Mail nicht angewendet.
      "send_rate": 100,                 // optional. Drosselungslimit.
                                        //           Begrenzt, wie viele Nachrichten pro Sekunde über alle Benutzer hinweg gesendet werden können.
                                        //           Hilft, eine Überlastung des Backends bei hohem Versandaufkommen zu verhindern.
      "send_rate_avoid": true,          // optional. Wenn auf true gesetzt, wird das Drosselungslimit nicht auf
                                        //           diese spezifische E-Mail angewendet.
    }]
  }
}

Antwort-Beispiele

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

403

{
  "status_code": 403,
  "status_message": "Token restrictions forbid this operation",
  "response": null
}

Tag-Bedingungen

Jede Tag-Bedingung ist ein Array wie [tagName, operator, operand], wobei

• tagName: Name eines Tags
• operator: “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
• operand: string | integer | array | date

Beschreibung der Operanden

• EQ: Tag-Wert ist gleich Operand;
• IN: Tag-Wert überschneidet sich mit Operand (Operand muss immer ein Array sein);
• NOTEQ: Tag-Wert ist nicht gleich einem Operanden;
• NOTIN: Tag-Wert überschneidet sich nicht mit Operand (Operand muss immer ein Array sein);
• GTE: Tag-Wert ist größer als oder gleich Operand;
• LTE: Tag-Wert ist kleiner als oder gleich Operand;
• BETWEEN: Tag-Wert ist größer als oder gleich dem min-Operand-Wert, aber kleiner als oder gleich dem max-Operand-Wert (Operand muss immer ein Array sein).

String-Tags

Gültige Operatoren: EQ, IN, NOTEQ, NOTIN
Gültige Operanden:

• EQ, NOTEQ: Operand muss ein String sein;
• IN, NOTIN: Operand muss ein Array von Strings sein wie ["value 1", "value 2", "value N"];

Integer-Tags

Gültige Operatoren: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Gültige Operanden:

• EQ, NOTEQ, GTE, LTE: Operand muss ein Integer sein;
• IN, NOTIN: Operand muss ein Array von Integern sein wie [value 1, value 2, value N];
• BETWEEN: Operand muss ein Array von Integern sein wie [min_value, max_value].

Datums-Tags

Gültige Operatoren: EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Gültige Operanden:

• "YYYY-MM-DD 00:00" (String)
• Unix-Zeitstempel 1234567890 (Integer)
• "N days ago" (String) für die Operatoren EQ, BETWEEN, GTE, LTE

Boolean-Tags

Gültige Operatoren: EQ
Gültige Operanden: 0, 1, true, false

Listen-Tags

Gültige Operatoren: IN
Gültige Operanden: Operand muss ein Array von Strings sein wie ["value 1", "value 2", "value N"].

Gefahr

Denken Sie daran, dass die Parameter „filter“ und „conditions“ nicht zusammen verwendet werden sollten.
Außerdem werden beide ignoriert, wenn der Parameter „devices“ in derselben Anfrage verwendet wird.

Hinweis

Länder- und Sprachtags

Der Wert des Sprachtags ist ein zweistelliger Kleinbuchstaben-Code gemäß ISO-639-1
Der Wert des Ländertags ist ein zweistelliger GROSSBUCHSTABEN-Code gemäß ISO_3166-2
Um beispielsweise eine Push-Benachrichtigung an portugiesischsprachige Abonnenten in Brasilien zu senden, müssen Sie die folgende Bedingung angeben: "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Registriert eine E-Mail-Adresse für die App.

POST https://api.pushwoosh.com/json/1.3/registerEmail

Request-Header

Name	Erforderlich	Wert	Beschreibung
Authorization	Ja	Token XXXX	API-Geräte-Token für den Zugriff auf die Device API. Ersetzen Sie XXXX durch Ihr tatsächliches API-Geräte-Token.

Request-Body

Name	Typ	Beschreibung
application*	string	Pushwoosh Application Code
email*	string	E-Mail-Adresse.
language	string	Sprachgebietsschema des Geräts. Muss ein zweistelliger Kleinbuchstaben-Code gemäß ISO-639-1-Standard sein.
userId	string	User ID zur Verknüpfung mit der E-Mail-Adresse.
tz_offset	integer	Zeitzonen-Offset in Sekunden.
tags	object	Tag-Werte, die dem registrierten Gerät zugewiesen werden sollen.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Beispiel

{
  "request": {
    "application": "APPLICATION_CODE",   // erforderlich. Pushwoosh Application Code.
    "email":"email@domain.com",          // erforderlich. E-Mail-Adresse, die registriert werden soll.
    "language": "en",                    // optional. Sprachgebietsschema.
    "userId": "userId",                  // optional. User ID zur Verknüpfung mit der E-Mail-Adresse.
    "tz_offset": 3600,                   // optional. Zeitzonen-Offset in Sekunden.
    "tags": {                            // optional. Tag-Werte, die für das registrierte Gerät gesetzt werden sollen.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // setzt die Liste der Werte für Tags vom Typ List
       "DateTag": "2024-10-02 22:11",    // beachten Sie, dass die Zeit in UTC sein sollte
       "BooleanTag": true                // gültige Werte sind: true, false
    }
  }
}

deleteEmail

Entfernt eine E-Mail-Adresse aus Ihrer Benutzerbasis.

POST https://api.pushwoosh.com/json/1.3/deleteEmail

Request-Header

Name	Erforderlich	Wert	Beschreibung
Authorization	Ja	Token XXXX	API-Geräte-Token für den Zugriff auf die Device API. Ersetzen Sie XXXX durch Ihr tatsächliches API-Geräte-Token.

Request-Body

Name	Typ	Beschreibung
application	string	Pushwoosh Application Code
email	string	E-Mail-Adresse, die in der /registerEmail-Anfrage verwendet wurde.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

Beispiel

{
  "request": {
    "application": "APPLICATION_CODE",  // erforderlich. Pushwoosh Application Code
    "email": "email@domain.com"         // erforderlich. E-Mail zum Löschen aus den App-Abonnenten.
  }
}

setEmailTags

Setzt Tag-Werte für die E-Mail-Adresse.

POST https://api.pushwoosh.com/json/1.3/setEmailTags

Request-Header

Name	Erforderlich	Wert	Beschreibung
Authorization	Ja	Token XXXX	API-Geräte-Token für den Zugriff auf die Device API. Ersetzen Sie XXXX durch Ihr tatsächliches API-Geräte-Token.

Request-Body

Name	Typ	Beschreibung
application	string	Pushwoosh Application Code
email	string	E-Mail-Adresse.
tags	object	JSON-Objekt der zu setzenden Tags, senden Sie ‘null’, um den Wert zu entfernen.
userId	string	User ID, die mit der E-Mail-Adresse verknüpft ist.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "skipped": []
  }
}

Beispiel

{
  "request": {
    "email": "email@domain.com",                  // erforderlich. E-Mail-Adresse, für die Tags gesetzt werden sollen.
    "application": "APPLICATION_CODE",            // erforderlich. Pushwoosh Application Code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // Zeit in UTC
      "BooleanTag": true                          // gültige Werte sind: true, false
    },
    "userId": "userId"                            // optional. User ID, die mit der E-Mail-Adresse verknüpft ist.
  }
}

Hinweis

Für andere Gerätetypen wird 200 OK zurückgegeben, obwohl Tags nicht gespeichert werden.

Vorsicht

Bitte vermeiden Sie es, mehr als 50 Tag-Werte in einer einzigen /setEmailTags-Anfrage zu setzen.

registerEmailUser

Verknüpft eine externe User ID mit einer angegebenen E-Mail-Adresse.

POST https://api.pushwoosh.com/json/1.3/registerEmailUser

Hinweis

Bitte beachten Sie, dass diese Methode keine E-Mail-Adresse in Ihrer Benutzerbasis registriert; sie sollte nur verwendet werden, um User IDs E-Mail-Adressen zuzuweisen, die bereits durch eine /registerEmail-Anfrage registriert wurden.

Kann im /createEmailMessage-API-Aufruf (Parameter ‘users’) verwendet werden.

Request-Header

Name	Erforderlich	Wert	Beschreibung
Authorization	Ja	Token XXXX	API-Geräte-Token für den Zugriff auf die Device API. Ersetzen Sie XXXX durch Ihr tatsächliches API-Geräte-Token.

Request-Body

Name	Typ	Beschreibung
application*	string	Pushwoosh Application Code
email*	string	E-Mail-Adresse.
userId*	string	User ID zur Verknüpfung mit der E-Mail-Adresse.
tz_offset	integer	Zeitzonen-Offset in Sekunden.

200

{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Request format is not valid."
}

403

{
  "status_code": 403,
  "status_message": "Forbidden."
}

Beispiel

{
  "request": {
    "application": "APPLICATION_CODE", // erforderlich. Pushwoosh Application Code.
    "email": "email@domain.com",       // erforderlich. Benutzer-E-Mail-Adresse.
    "userId": "userId",                // erforderlich. User ID zur Verknüpfung mit der E-Mail-Adresse.
    "tz_offset": 3600                  // optional. Zeitzonen-Offset in Sekunden.
  }
}

Hinweis

Um Daten zu Soft Bounces, Hard Bounces und E-Mail-Beschwerden abzurufen, einschließlich Datum, E-Mail-Adresse und Grund für jeden Bounce, verwenden Sie die BouncedEmails-Methode.