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 die Migrationsanleitung.

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-Zugriffstoken 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 Notifications-Parameter unten.

Tipp

Übergeben Sie einen X-Request-ID-Header, um die erstellte Nachricht mit Ihrer Anfrage für eine durchgängige Nachverfolgung zu korrelieren – siehe Request ID.

Notifications-Parameter

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-Vorlagencode. 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, ohne die Zeitzonen der Benutzer zu berücksichtigen.
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 zugestellt (registriert über den /registerEmail-Aufruf). 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 Standardeinstellungen in den Anwendungseigenschaften zu überschreiben.
reply-to	object	Nein	Geben Sie eine benutzerdefinierte Antwort-E-Mail-Adresse 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 weggelassen, wird die Nachricht als transaktional behandelt und an alle zugestellt, einschließlich der Kontrollgruppe. Marketing-Nachrichten werden nicht an Mitglieder der Kontrollgruppe zugestellt.
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 spezielle 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 spezielle 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, treated as transactional: delivered to everyone.
                                        // Marketing messages are not delivered to control group members.
      "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
}

210

{
  "status_code": 210,
  "status_message": "Preset content is not approved",
  "response": null
}

403

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

Hinweis

Ein 210 mit "Preset content is not approved" bedeutet, dass die Inhaltsgenehmigung für Ihr Konto aktiviert ist und die Vorlage (preset) noch nicht genehmigt wurde. Senden und genehmigen Sie sie unter Inhalt → E-Mail-Inhalt, bevor Sie senden.

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

Operandenbeschreibung

• 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 minimalen Operandenwert, aber kleiner oder gleich dem maximalen 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 ganze Zahl sein;
• IN, NOTIN: Operand muss ein Array von ganzen Zahlen sein, wie [value 1, value 2, value N];
• BETWEEN: Operand muss ein Array von ganzen Zahlen 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

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 GROSSBUCHSTABENCODE 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ätetoken.

Anfrage-Hauptteil

Name	Typ	Beschreibung
application*	string	Pushwoosh-Anwendungscode
email*	string	E-Mail-Adresse.
language	string	Sprach-Locale, das mit dem Kontakt verknüpft werden soll. Es gibt kein Gerät, von dem es gelesen werden kann, also übergeben Sie es hier explizit oder legen Sie es später über Tags fest. Ein Kontakt, der ohne dieses Attribut bleibt, wird für keine Sprache gezählt und erhält die E-Mail in der Standardsprache. 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 sollte.

status_code	Bedeutung	Wiederholen?
200	Erfolg – die E-Mail-Adresse ist registriert.	Nein – erledigt.
210	Argument-/Validierungsfehler – die Anfrage wurde verstanden, aber abgelehnt (Adresse auf der Blacklist, ungültige oder Wegwerf-E-Mail, falsche Plattform für den Plan des Kontos). Siehe 210-Fehlermeldungen unten.	Nein – dieselbe Anfrage gibt denselben 210-Code zurück. Protokollieren Sie die Adresse und überspringen Sie sie.
400	Fehlerhafte Anfrage – ungültiges JSON oder ein fehlendes Pflichtfeld.	Nein – korrigieren Sie die Anfrage, wiederholen Sie sie nicht.
403	Verboten – ungültiges oder eingeschränktes Gerätetoken.	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, sodass eine unveränderte Wiederholung zum selben Ergebnis führt. 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 Unterdrückungsliste 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 dem @ 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 „Nur E-Mail“-Plan und kann keine Nicht-E-Mail-Geräte registrieren.

Hinweis

Nur permanente (harte) Bounces fügen eine Adresse zur Blacklist 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	API-Gerätetoken für den Zugriff auf die Geräte-API. Ersetzen Sie XXXX durch Ihr tatsächliches Gerätetoken.

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

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

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ätetoken.

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 registriert in Ihrer Benutzerbasis; 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 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ätetoken.

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 weichen Bounces, harten Bounces und E-Mail-Beschwerden abzurufen, einschließlich Datum, E-Mail-Adresse und Grund für jeden Bounce, verwenden Sie die Methode BouncedEmails.