E-Mail-API

/createEmailMessage ist veraltet

Neue Integrationen sollten die Messaging API v2 verwenden – übergeben Sie platforms: ["EMAIL"] und einen email_payload-Block an Notify. Siehe den Migrationsleitfaden.

createEmailMessage Veraltet

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-Zugangstoken aus dem Pushwoosh Control Panel.
application	string	Ja	Pushwoosh-Anwendungscode
notifications	array	Ja	JSON-Array, das Details zur E-Mail-Nachricht enthält. 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 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 (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 User-IDs (registriert über den /registerEmail-Aufruf) zugestellt. Nicht mehr als 1000 User-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.
bcc	array	Nein	BCC (Blind Carbon Copy): Array von E-Mail-Adressen, die eine Kopie der E-Mail erhalten, ohne dass andere Empfänger sie sehen.
email_type	string	Nein	Geben Sie den E-Mail-Typ an: "marketing" oder "transactional". Wenn nicht angegeben, erhalten Benutzer mit PW_ControlGroup: true die Nachricht nicht.
email_category	string	Erforderlich, wenn email_type "marketing" ist.	Geben Sie einen der im Abonnement-Präferenzzentrum konfigurierten Kategorienamen an (z. B. Newsletter, Werbeaktion, 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 über alle Benutzer hinweg 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",         // required. API access token from Pushwoosh Control Panel
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code.
    "notifications": [{
      "send_date": "now",               // required. YYYY-MM-DD HH:mm  OR 'now'
      "preset": "ERXXX-32XXX",          // required. Copy Email preset code from the URL bar of
                                        //           the Email Content editor page in Pushwoosh Control Panel.
      "subject": {                      // optional. Email message subject line.
        "de": "subject de",
        "en": "subject en"
      },
      "content": {                      // optional. Email body content.
        "de": "<html><body>de Hello, moto</body></html>",
        "default": "<html><body>default Hello, moto</body></html>"
      },
      "attachments": [{                 // optional. Email attachments
        "name": "image.png",            //           "name" - file name
        "content": "iVBANA...AFTkuQmwC" //           "content" - base64 encoded content of the file
      }, {
        "name": "file.pdf",
        "content": "JVBERi...AFTarEGC"
      }],
      "list_unsubscribe": "URL",        // optional. Allow to set custom URL for "Link-Unsubscribe" header
      "campaign": "CAMPAIGN_CODE",      // optional. To assign this email message to a particular campaign,
                                        //           add a campaign code here.
      "ignore_user_timezone": true,     // optional.
      "timezone": "America/New_York",   // optional. Specify to send the message according to
                                        //           timezone set on user's device.
      "filter": "FILTER_NAME",          // optional. Send the message to specific users meeting filter conditions.
      "devices": [                      // optional. Specify email addresses to send targeted email messages.
        "email_address1",               //           Not more than 1000 addresses in an array.
        "email_address2"                //           If set, the message will only be sent to the addresses on
      ],                                //           the list. Ignored if the Application Group is used.
      "use_auto_registration": true,    // optional. Automatically register emails specified in "devices" parameter
      "users": [                        // optional. If set, the email message will only be delivered to the
        "userId1",                      //           specified user IDs (registered via /registerEmail call).
        "userId2"                       //           Not more than 1000 user IDs in an array.
      ],                                //           If the "devices" parameter is specified,
                                        //           the "users" parameter will be ignored.
      "dynamic_content_placeholders": { // optional. Placeholders for dynamic content instead of device tag values.
        "firstname": "John",
        "firstname_en": "John"
      },
      "conditions": [                   // optional. Segmentation conditions, see remark below.
        ["Country", "EQ", "BR"],
        ["Language", "EQ", "pt"]
      ],
      "from": {                         // optional. Specify a sender name and sender email address
        "name": "alias from",           //           to replace the default "From name" and "From email"
        "email": "from-email@email.com" //           set up in application properties.
      },
      "reply-to": {                     // optional. Specify an email address to replace the
        "name": "alias reply to ",      //           default "Reply to" set up in application properties.
        "email": "reply-to@email.com"
      },
      "bcc": [                          // optional. BCC: array of email addresses that receive a copy without other recipients seeing them.
        "bcc1@example.com",
        "bcc2@example.com"
      ],
      "email_type": "marketing",        // optional. "marketing" or "transactional".
                                        // If omitted, users with PW_ControlGroup: true will not receive the message.
      "email_category": "category name",// required when email_type is "marketing". Category name.
      "transactionId": "unique UUID",   // optional. Unique message identifier to prevent re-sending
                                        //           in case of network problems. Stored on the side
                                        //           of Pushwoosh for 5 minutes.
      // Frequency capping params. Ensure that Global frequency capping is configured in the Control Panel.
      // Frequency capping does not apply to transactional messages.
      // In all other cases, including omitted "email_type", frequency capping applies.
      "capping_days": 30,               // optional. Amount of days for frequency capping (max 30 days)
      "capping_count": 10,              // optional. The max number of emails that can be sent from a
                                        //           specific app to a particular device within a 'capping_days'
                                        //           period. In case the message created exceeds the
                                        //           'capping_count' limit for a device, it won't
                                        //           be sent to that device.
      "capping_exclude": true,          // optional. If set to true, this email will not
                                        //           be counted towards the capping for future emails.
      "capping_avoid": true,            // optional. If set to true, capping will not be applied to
                                        //           this specific email.
      "send_rate": 100,                 // optional. Throttling limit.
                                        //           Limit how many messages can be sent per second across all users.
                                        //           Helps prevent backend overload during high-volume sends.
      "send_rate_avoid": true,          // optional. If set to true, throttling limit will not be applied to
                                        //           this specific email.
    }]
  }
}

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: string | integer | array | date

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 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 eine Ganzzahl sein;
• IN, NOTIN: Operand muss ein Array von Ganzzahlen sein, wie [value 1, value 2, value N];
• BETWEEN: Operand muss ein Array von Ganzzahlen 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 (Ganzzahl)
• "N days ago" (String) 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 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 Sprach-Tags

Der Wert des Sprach-Tags ist ein zweibuchstabiger Kleinbuchstabencode gemäß ISO-639-1
Der Wert des Länder-Tags ist ein zweibuchstabiger 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	Geräte-API-Token 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 zweibuchstabiger Kleinbuchstabencode gemäß dem ISO-639-1-Standard sein.
userId	string	User-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
}

210

{
  "status_code": 210,
  "status_message": "this hwid (email) is blacklisted",
  "response": null
}

400

{
  "status_code": 400,
  "status_message": "Missing required argument: email",
  "response": null
}

403

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

500

{
  "status_code": 500,
  "status_message": "Internal server error",
  "response": null
}

Beispiel

{
  "request": {
    "application": "APPLICATION_CODE",   // required. Pushwoosh application code.
    "email":"email@domain.com",          // required. Email address to be registered.
    "language": "en",                    // optional. Language locale.
    "userId": "userId",                  // optional. User ID to associate with the email address.
    "tz_offset": 3600,                   // optional. Timezone offset in seconds.
    "tags": {                            // optional. Tag values to set for the device registered.
       "StringTag": "string value",
       "IntegerTag": 42,
       "ListTag": ["string1","string2"], // sets the list of values for Tags of List type
       "DateTag": "2024-10-02 22:11",    // note the time should be in UTC
       "BooleanTag": true                // valid values are: true, false
    }
  }
}

Antwortcodes

Die öffentliche API gibt das Ergebnis in status_code zurück. Verwenden Sie die folgende Tabelle, um zu entscheiden, ob ein fehlgeschlagener Aufruf wiederholt werden soll.

status_code	Bedeutung	Wiederholen?
200	Erfolg — die E-Mail-Adresse ist registriert.	Nein — fertig.
210	Argument-/Validierungsfehler — die Anfrage wurde verstanden, aber abgelehnt (gesperrte Adresse, ungültige oder Wegwerf-E-Mail, falsche Plattform für den Kontoplan). Siehe 210-Fehlermeldungen unten.	Nein — dieselbe Anfrage gibt denselben 210-Fehler zurück. Protokollieren Sie die Adresse und überspringen Sie sie.
400	Fehlerhafte Anfrage — ungültiges JSON oder ein fehlendes erforderliches Feld.	Nein — korrigieren Sie die Anfrage, wiederholen Sie sie nicht.
403	Verboten — ungültiges oder eingeschränktes Geräte-API-Token.	Nein — korrigieren Sie die Autorisierung.
500	Interner Serverfehler — vorübergehendes Infrastrukturproblem oder Zeitüberschreitung.	Ja, mit exponentiellem Backoff — der einzige vorübergehende Fall.

Tipp

Wiederholen Sie nur 500-Antworten mit exponentiellem Backoff — dies ist der einzige vorübergehende Fall. Ein 210, 400 oder 403 ist endgültig: Der Server hat Ihre Anfrage verstanden und abgelehnt, daher führt eine unveränderte Wiederholung zum selben Ergebnis. Protokollieren Sie stattdessen die Adresse (bei 210) oder korrigieren Sie die Anfrage/das Token (bei 400/403).

210-Fehlermeldungen

Eine 210-Antwort enthält den spezifischen Grund in status_message.

status_message	Bedeutung
this hwid (email) is blacklisted	Die Adresse befindet sich auf der Sperrliste nach einem permanenten (harten) Bounce und wird nicht erneut registriert.
hwid (email) is invalid / has invalid semantic	Die Adresse besteht die Validierung nicht.
hwid (email) is empty	Es wurde keine Adresse angegeben.
hwid (email) has invalid count of parts	Fehlendes oder zusätzliches @.
hwid (email) has invalid local part	Der Teil vor @ ist ungültig.
hwid (email) has invalid domain part	Der Domain-Teil ist ungültig.
hwid (email) has disposable domain	Die Adresse verwendet eine Wegwerf-/temporäre E-Mail-Domain (z. B. 10minutemail).
hwid is not valid	Die hwid selbst ist fehlerhaft formatiert.
only email platform allowed for Email Only subscription	Das Konto hat einen reinen E-Mail-Plan und kann keine Nicht-E-Mail-Geräte registrieren.

Hinweis

Nur permanente (harte) Bounces fügen eine Adresse zur Sperrliste hinzu. Weiche Bounces und Spam-Beschwerden blockieren registerEmail nicht — nur this hwid (email) is blacklisted spiegelt die Unterdrückung wider.

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	Geräte-API-Token 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",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

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	Geräte-API-Token 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	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",                  // required. Email address to set tags for.
    "application": "APPLICATION_CODE",            // required. Pushwoosh application code.
    "tags": {
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",              // time in UTC
      "BooleanTag": true                          // valid values are: true, false
    },
    "userId": "userId"                            // optional. User ID associated with the email address.
  }
}

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 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 zur Zuweisung von User-IDs zu E-Mail-Adressen verwendet werden, 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	Geräte-API-Token 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	User-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", // required. Pushwoosh application code.
    "email": "email@domain.com",       // required. User email address.
    "userId": "userId",                // required. User ID to associate with the email address.
    "tz_offset": 3600                  // optional. Timezone offset in seconds.
  }
}

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.