E-Mail-API

createEmailMessage

Erstellt eine E-Mail-Nachricht.

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

Parameter des Anfrage-Hauptteils

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

Benachrichtigungsparameter

Name	Typ	Erforderlich	Beschreibung
send_date	string	Ja	Definiert, wann die E-Mail gesendet werden soll. Format: YYYY-MM-DD HH:mm oder "now".
preset	string	Ja	E-Mail-Preset-Code. Kopieren Sie ihn aus der URL-Leiste des E-Mail-Inhaltseditors 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, ist der Betreff leer.
content	string oder object	Nein	Der Inhalt des E-Mail-Hauptteils. Kann eine Zeichenkette 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 (base64-kodiert) nicht überschreiten.
list_unsubscribe	string	Nein	Ermöglicht das Festlegen 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, wobei die Zeitzonen der Benutzer ignoriert werden.
timezone	string	Nein	Sendet die E-Mail entsprechend 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) zum Senden gezielter E-Mails. Bei Verwendung wird die Nachricht nur an diese Adressen gesendet. Wird ignoriert, wenn die Anwendungsgruppe verwendet wird.
use_auto_registration	boolean	Nein	Wenn true, werden E-Mails aus dem devices-Parameter automatisch registriert.
users	array	Nein	Wenn festgelegt, wird die E-Mail-Nachricht nur an die angegebenen Benutzer-IDs (registriert über den /registerEmail-Aufruf) zugestellt. Nicht mehr als 1000 Benutzer-IDs in einem Array. Wenn der „devices“-Parameter angegeben ist, wird der „users“-Parameter ignoriert.
dynamic_content_placeholders	object	Nein	Platzhalter für dynamische Inhalte 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 die Standardeinstellung in den Anwendungseigenschaften zu überschreiben.
reply-to	object	Nein	Geben Sie eine benutzerdefinierte Antwort-E-Mail an, um die Standardeinstellung in den Anwendungseigenschaften zu überschreiben.
email_type	string	Nein	Geben Sie den E-Mail-Typ an: "marketing" oder "transactional".
email_category	string	Erforderlich, wenn email_type "marketing" ist.	Geben Sie einen der Kategorienamen an, die im Abonnement-Präferenzzentrum konfiguriert sind (z. B. Newsletter, Werbeaktionen, Produkt-Updates).
transactionId	string	Nein	Eindeutiger Nachrichtenidentifikator, um ein erneutes Senden bei Netzwerkproblemen zu verhindern. Wird auf der Seite von Pushwoosh für 5 Minuten gespeichert.
capping_days	integer	Nein	Die Anzahl der Tage (max. 30), für die das Frequency Capping pro Gerät angewendet wird. Hinweis: Stellen Sie sicher, dass das globale 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 capping_days-Zeitraums gesendet werden können. Falls die erstellte Nachricht das capping_count-Limit 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 das Capping nicht auf diese spezifische E-Mail angewendet.
send_rate	integer	Nein	Begrenzen Sie, wie viele Nachrichten pro Sekunde an alle Benutzer gesendet werden können. Hilft, eine Überlastung des Backends bei hohem Sendungsvolumen zu vermeiden.
send_rate_avoid	boolean	Nein	Wenn auf true gesetzt, wird das Drosselungslimit nicht auf diese spezifische E-Mail angewendet.

Anfragebeispiel

{
  "request": {
    "auth": "API_ACCESS_TOKEN",         // erforderlich. API-Zugriffstoken aus dem Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // erforderlich. Pushwoosh-Anwendungscode.
    "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 E-Mail-Inhaltseditor-Seite im Pushwoosh Control Panel.
      "subject": {                      // optional. Betreffzeile der E-Mail-Nachricht.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Inhalt des E-Mail-Hauptteils.
        "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. Ermöglicht das Festlegen 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 an, um die Nachricht entsprechend 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 festgelegt, wird die Nachricht nur an die Adressen auf
      ],                                //           der Liste gesendet. Wird ignoriert, wenn die Anwendungsgruppe verwendet wird.
      "use_auto_registration": true,    // optional. E-Mails, die im Parameter „devices“ angegeben sind, automatisch registrieren
      "users": [                        // optional. Wenn festgelegt, wird die E-Mail-Nachricht nur an die
        "userId1",                      //           angegebenen Benutzer-IDs (registriert über den /registerEmail-Aufruf) zugestellt.
        "userId2"                       //           Nicht mehr als 1000 Benutzer-IDs in einem Array.
      ],                                //           Wenn der „devices“-Parameter angegeben ist,
                                        //           wird der „users“-Parameter ignoriert.
      "dynamic_content_placeholders": { // optional. Platzhalter für dynamische Inhalte 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 standardmäßigen „Von-Namen“ und die „Von-E-Mail“
        "email": "from-email@email.com" //           zu ersetzen, die in den Anwendungseigenschaften eingerichtet sind.
      },
      "reply-to": {                     // optional. Geben Sie eine E-Mail-Adresse an, um die
        "name": "alias reply to ",      //           standardmäßige „Antwort an“ zu ersetzen, die in den Anwendungseigenschaften eingerichtet ist.
        "email": "reply-to@email.com"
      },
      "email_type": "marketing",        // optional. „marketing“ oder „transactional“.
      "email_category": "category name",// erforderlich, wenn email_type „marketing“ ist. Kategoriename.
      "transactionId": "unique UUID",   // optional. Eindeutiger Nachrichtenidentifikator, um ein erneutes Senden
                                        //           bei Netzwerkproblemen zu verhindern. Wird auf der Seite
                                        //           von Pushwoosh für 5 Minuten gespeichert.
      // Frequency-Capping-Parameter. Stellen Sie sicher, dass das globale Frequency Capping im Control Panel konfiguriert ist.
      "capping_days": 30,               // optional. Anzahl der Tage für das 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 'capping_days'-
                                        //           Zeitraums gesendet werden können. Falls die erstellte Nachricht das
                                        //           'capping_count'-Limit 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 das Capping nicht auf
                                        //           diese spezifische E-Mail angewendet.
      "send_rate": 100,                 // optional. Drosselungslimit.
                                        //           Begrenzen Sie, wie viele Nachrichten pro Sekunde an alle Benutzer gesendet werden können.
                                        //           Hilft, eine Überlastung des Backends bei hohem Sendungsvolumen zu vermeiden.
      "send_rate_avoid": true,          // optional. Wenn auf true gesetzt, wird das Drosselungslimit nicht auf
                                        //           diese spezifische E-Mail angewendet.
    }]
  }
}

Antwortbeispiele

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: Zeichenkette | Ganzzahl | Array | Datum

Beschreibung des Operanden

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

String-Tags

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

• EQ, NOTEQ: Operand muss eine Zeichenkette sein;
• IN, NOTIN: Operand muss ein Array von Zeichenketten sein, wie ["Wert 1", "Wert 2", "Wert N"];

Integer-Tags

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

• EQ, NOTEQ, GTE, LTE: Operand muss eine Ganzzahl sein;
• IN, NOTIN: Operand muss ein Array von Ganzzahlen sein, wie [Wert 1, Wert 2, Wert N];
• BETWEEN: Operand muss ein Array von Ganzzahlen sein, wie [min_wert, max_wert].

Datums-Tags

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

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

Boolesche 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 Zeichenketten sein, wie ["Wert 1", "Wert 2", "Wert 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 Sprach-Tags

Der Wert des Sprach-Tags ist ein zweistelliger Kleinbuchstabencode gemäß ISO-639-1
Der Wert des Länder-Tags 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

Anfrage-Header

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

Anfrage-Hauptteil

Name	Typ	Beschreibung
application*	string	Pushwoosh-Anwendungscode
email*	string	E-Mail-Adresse.
language	string	Sprach-Locale des Geräts. Muss ein zweistelliger Kleinbuchstabencode gemäß dem ISO-639-1-Standard sein.
userId	string	Benutzer-ID, die mit der E-Mail-Adresse verknüpft werden soll.
tz_offset	integer	Zeitzonenversatz 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-Anwendungscode.
    "email":"email@domain.com",          // erforderlich. Zu registrierende E-Mail-Adresse.
    "language": "en",                    // optional. Sprach-Locale.
    "userId": "userId",                  // optional. Benutzer-ID, die mit der E-Mail-Adresse verknüpft werden soll.
    "tz_offset": 3600,                   // optional. Zeitzonenversatz in Sekunden.
    "tags": {                            // optional. Tag-Werte, die für das registrierte Gerät festgelegt werden sollen.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // setzt die Liste der Werte für Tags vom Typ Liste
       "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

Anfrage-Header

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

Anfrage-Hauptteil

Name	Typ	Beschreibung
application	string	Pushwoosh-Anwendungscode
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-Anwendungscode
    "email": "email@domain.com"         // erforderlich. E-Mail, die aus den App-Abonnenten gelöscht werden soll.
  }
}

setEmailTags

Legt Tag-Werte für die E-Mail-Adresse fest.

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

Anfrage-Header

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

Anfrage-Hauptteil

Name	Typ	Beschreibung
application	string	Pushwoosh-Anwendungscode
email	string	E-Mail-Adresse.
tags	object	JSON-Objekt der zu setzenden Tags, senden Sie ‘null’, um den Wert zu entfernen.
userId	string	Benutzer-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 festgelegt werden sollen.
    "application": "APPLICATION_CODE",            // erforderlich. Pushwoosh-Anwendungscode.
    "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. Benutzer-ID, die mit der E-Mail-Adresse verknüpft ist.
  }
}

Hinweis

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

Vorsicht

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

registerEmailUser

Verknüpft eine externe Benutzer-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 Benutzer-IDs E-Mail-Adressen zuzuweisen, die bereits durch eine /registerEmail-Anfrage registriert wurden.

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

Anfrage-Header

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

Anfrage-Hauptteil

Name	Typ	Beschreibung
application*	string	Pushwoosh-Anwendungscode
email*	string	E-Mail-Adresse.
userId*	string	Benutzer-ID, die mit der E-Mail-Adresse verknüpft werden soll.
tz_offset	integer	Zeitzonenversatz 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-Anwendungscode.
    "email": "email@domain.com",       // erforderlich. E-Mail-Adresse des Benutzers.
    "userId": "userId",                // erforderlich. Benutzer-ID, die mit der E-Mail-Adresse verknüpft werden soll.
    "tz_offset": 3600                  // optional. Zeitzonenversatz 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 Methode BouncedEmails.