API E-mail

/createEmailMessage est obsolète

Les nouvelles intégrations devraient utiliser l’API de Messagerie v2 — passez platforms: ["EMAIL"] et un bloc email_payload à Notify. Consultez le guide de migration.

createEmailMessage Obsolète

Crée un message e-mail.

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

Paramètres du corps de la requête

Nom	Type	Requis	Description
auth	string	Oui	Jeton d’accès API depuis le Panneau de Contrôle Pushwoosh.
application	string	Oui	Code d’application Pushwoosh
notifications	array	Oui	Tableau JSON contenant les détails du message e-mail. Voir le tableau Paramètres de Notifications ci-dessous.

Conseil

Passez un en-tête X-Request-ID pour corréler le message créé avec votre requête pour un traçage de bout en bout — voir ID de Requête.

Paramètres de Notifications

Nom	Type	Requis	Description
send_date	string	Oui	Définit quand envoyer l’e-mail. Format : AAAA-MM-JJ HH:mm ou « now ».
preset	string	Oui	Code de préréglage d’e-mail. Copiez depuis la barre d’URL de l’Éditeur de Contenu d’E-mail dans le Panneau de Contrôle Pushwoosh.
subject	string ou object	Non	Ligne d’objet de l’e-mail. L’e-mail sera toujours dans la langue du contenu. Si subject ne contient pas de langue correspondante pour content, l’objet sera vide.
content	string ou object	Non	Le contenu du corps de l’e-mail. Peut être une chaîne de caractères pour du contenu HTML simple ou un objet pour des versions localisées.
attachments	array	Non	Les pièces jointes de l’e-mail. Seules deux pièces jointes sont disponibles. Chaque pièce jointe ne doit pas dépasser 1 Mo (encodée en base64).
list_unsubscribe	string	Non	Permet de définir une URL personnalisée pour l’en-tête « Link-Unsubscribe ».
campaign	string	Non	Code de campagne pour associer l’e-mail à une campagne spécifique.
campaign_name	string	Non	Nom interne de ce message, affiché comme titre de la ligne dans Message History et dans son export. Sans lien avec campaign ci-dessus. Il ne groupe pas les messages et n’affecte pas la remise. Maximum 255 caractères. Vide, il revient à l’objet de l’e-mail lui-même.
ignore_user_timezone	boolean	Non	Si true, envoie l’e-mail immédiatement, en ignorant les fuseaux horaires des utilisateurs.
timezone	string	Non	Envoie l’e-mail en fonction du fuseau horaire de l’utilisateur. Exemple : « America/New_York ».
filter	string	Non	Envoie l’e-mail aux utilisateurs correspondant à une condition de filtre spécifique.
devices	array	Non	Liste d’adresses e-mail (max 1000) pour envoyer des e-mails ciblés. Si utilisée, le message n’est envoyé qu’à ces adresses. Ignorée si le Groupe d’Applications est utilisé.
use_auto_registration	boolean	Non	Si true, enregistre automatiquement les e-mails du paramètre devices.
users	array	Non	Si défini, le message e-mail ne sera livré qu’aux ID Utilisateur spécifiés (enregistrés via l’appel /registerEmail). Pas plus de 1000 ID utilisateur dans un tableau. Si le paramètre « devices » est spécifié, le paramètre « users » sera ignoré.
dynamic_content_placeholders	object	Non	Espaces réservés pour le contenu dynamique au lieu des valeurs de tag de l’appareil.
conditions	array	Non	Conditions de segmentation utilisant des tags. Exemple : [["Country", "EQ", "BR"]].
from	object	Non	Spécifiez un nom d’expéditeur et un e-mail personnalisés, remplaçant les valeurs par défaut dans les propriétés de l’application.
reply-to	object	Non	Spécifiez un e-mail de réponse personnalisé, remplaçant la valeur par défaut dans les propriétés de l’application.
bcc	array	Non	CCI (Copie Carbone Invisible) : tableau d’adresses e-mail qui reçoivent une copie de l’e-mail sans que les autres destinataires ne les voient.
email_type	string	Non	Spécifiez le type d’e-mail : « marketing » ou « transactional ». Si omis, le message est traité comme transactionnel et livré à tout le monde, y compris le groupe de contrôle. Les messages marketing ne sont pas livrés aux membres du groupe de contrôle.
email_category	string	Requis lorsque email_type est « marketing ».	Spécifiez l’un des noms de catégorie configurés dans le centre de préférences d’abonnement (par ex. Newsletter, Promotionnel, Mises à jour de produit).
transactionId	string	Non	Identifiant de message unique pour éviter le renvoi en cas de problèmes réseau. Stocké du côté de Pushwoosh pendant 5 minutes.
capping_days	integer	Non	Le nombre de jours (max 30) pour appliquer le plafonnement de fréquence par appareil. Note : Assurez-vous que le Plafonnement de fréquence global est configuré dans le Panneau de Contrôle.
capping_count	integer	Non	Le nombre maximum d’e-mails pouvant être envoyés depuis une application spécifique à un appareil particulier pendant une période de capping_days. Si le message créé dépasse la limite capping_count pour un appareil, il ne sera pas envoyé à cet appareil.
capping_exclude	boolean	Non	Si défini sur true, cet e-mail ne sera pas comptabilisé pour le plafonnement des futurs e-mails.
capping_avoid	boolean	Non	Si défini sur true, le plafonnement ne sera pas appliqué à cet e-mail spécifique.
send_rate	integer	Non	Limitez le nombre de messages pouvant être envoyés par seconde à l’ensemble des utilisateurs. Aide à prévenir la surcharge du backend lors d’envois à grand volume.
send_rate_avoid	boolean	Non	Si défini sur true, la limite de régulation ne sera pas appliquée à cet e-mail spécifique.

Exemple de requête

{
  "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.
      "campaign_name": "Black Friday",  // optional. Internal name for this message, shown as
                                        //           the row title in Message History and in its
                                        //           export. Max 255 characters. Empty falls back
                                        //           to the email's own subject line.
      "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.
    }]
  }
}

Exemples de réponses

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
}

Note

Un code 210 avec « Preset content is not approved » signifie que l’approbation de contenu est activée pour votre compte et que le preset n’est pas encore Approuvé. Soumettez-le et approuvez-le depuis Contenu → Contenu d’e-mail avant de l’envoyer.

Conditions de tag

Chaque condition de tag est un tableau comme [nomTag, opérateur, opérande] où

• nomTag : nom d’un tag
• opérateur : “EQ” | “IN” | “NOTEQ” | “NOTIN” | “LTE” | “GTE” | “BETWEEN”
• opérande : chaîne de caractères | entier | tableau | date

Description de l’opérande

• EQ : la valeur du tag est égale à l’opérande ;
• IN : la valeur du tag croise l’opérande (l’opérande doit toujours être un tableau) ;
• NOTEQ : la valeur du tag n’est pas égale à un opérande ;
• NOTIN : la valeur du tag ne croise pas l’opérande (l’opérande doit toujours être un tableau) ;
• GTE : la valeur du tag est supérieure ou égale à l’opérande ;
• LTE : la valeur du tag est inférieure ou égale à l’opérande ;
• BETWEEN : la valeur du tag est supérieure ou égale à la valeur minimale de l’opérande mais inférieure ou égale à la valeur maximale de l’opérande (l’opérande doit toujours être un tableau).

Tags de type chaîne de caractères

Opérateurs valides : EQ, IN, NOTEQ, NOTIN
Opérandes valides :

• EQ, NOTEQ : l’opérande doit être une chaîne de caractères ;
• IN, NOTIN : l’opérande doit être un tableau de chaînes de caractères comme ["valeur 1", "valeur 2", "valeur N"] ;

Tags de type entier

Opérateurs valides : EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Opérandes valides :

• EQ, NOTEQ, GTE, LTE : l’opérande doit être un entier ;
• IN, NOTIN : l’opérande doit être un tableau d’entiers comme [valeur 1, valeur 2, valeur N] ;
• BETWEEN : l’opérande doit être un tableau d’entiers comme [valeur_min, valeur_max].

Tags de type date

Opérateurs valides : EQ, IN, NOTEQ, NOTIN, BETWEEN, GTE, LTE
Opérandes valides :

• "AAAA-MM-JJ 00:00" (chaîne de caractères)
• timestamp unix 1234567890 (entier)
• "Il y a N jours" (chaîne de caractères) pour les opérateurs EQ, BETWEEN, GTE, LTE

Tags de type booléen

Opérateurs valides : EQ
Opérandes valides : 0, 1, true, false

Tags de type liste

Opérateurs valides : IN
Opérandes valides : l’opérande doit être un tableau de chaînes de caractères comme ["valeur 1", "valeur 2", "valeur N"].

Danger

N’oubliez pas que les paramètres « filter » et « conditions » ne doivent pas être utilisés ensemble.
De plus, ils seront tous les deux ignorés, si le paramètre « devices » est utilisé dans la même requête.

Note

Tags de Pays et de Langue

La valeur du tag de langue est un code à deux lettres en minuscules selon la norme ISO-639-1
La valeur du tag de pays est un code à deux lettres en MAJUSCULES selon la norme ISO_3166-2
Par exemple, pour envoyer une notification push à des abonnés lusophones au Brésil, vous devrez spécifier la condition suivante : "conditions": [["Country", "EQ", "BR"],["Language", "EQ", "pt"]]

registerEmail

Enregistre une adresse e-mail pour l’application.

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

En-têtes de la requête

Nom	Requis	Valeur	Description
Authorization	Oui	Token XXXX	Jeton d’API d’Appareil pour accéder à l’API d’Appareil. Remplacez XXXX par votre jeton d’API d’Appareil réel.

Corps de la requête

Nom	Type	Description
application*	string	Code d’application Pushwoosh
email*	string	Adresse e-mail.
language	string	Locale de langue à associer au contact. Il n’y a pas d’appareil pour la lire, donc passez-la explicitement ici, ou définissez-la plus tard via les Tags. Un contact laissé sans cette information n’est compté pour aucune langue et reçoit l’e-mail dans la langue par défaut. Doit être un code à deux lettres en minuscules selon la norme ISO-639-1.
userId	string	ID Utilisateur à associer à l’adresse e-mail.
tz_offset	integer	Décalage de fuseau horaire en secondes.
tags	object	Valeurs de tag à assigner à l’appareil enregistré.

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
}

Exemple

{
  "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
    }
  }
}

Codes de réponse

L’API publique renvoie le résultat dans status_code. Utilisez le tableau ci-dessous pour décider si un appel échoué doit être réessayé.

status_code	Signification	Réessayer ?
200	Succès — l’adresse e-mail est enregistrée.	Non — terminé.
210	Erreur d’argument/validation — la requête a été comprise mais rejetée (adresse sur liste noire, e-mail invalide ou jetable, mauvaise plateforme pour le plan du compte). Voir les messages d’erreur 210 ci-dessous.	Non — la même requête renverra le même 210. Enregistrez l’adresse et ignorez-la.
400	Requête malformée — JSON invalide ou champ obligatoire manquant.	Non — corrigez la requête, ne la répétez pas.
403	Interdit — jeton d’API d’appareil invalide ou restreint.	Non — corrigez l’autorisation.
500	Erreur interne du serveur — problème d’infrastructure temporaire ou timeout.	Oui, avec un backoff exponentiel — le seul cas transitoire.

Conseil

Ne réessayez que les réponses 500, en utilisant un backoff exponentiel — c’est le seul cas transitoire. Un 210, 400 ou 403 est final : le serveur a compris votre requête et l’a rejetée, donc la répéter sans modification renverra le même résultat. Enregistrez plutôt l’adresse (pour 210) ou corrigez la requête/le jeton (pour 400/403).

Messages d’erreur 210

Une réponse 210 contient la raison spécifique dans status_message.

status_message	Signification
this hwid (email) is blacklisted	L’adresse est sur la liste de suppression après un rebond permanent (hard bounce) et ne sera pas réenregistrée.
hwid (email) is invalid / has invalid semantic	L’adresse échoue à la validation.
hwid (email) is empty	Aucune adresse n’a été fournie.
hwid (email) has invalid count of parts	@ manquant ou en trop.
hwid (email) has invalid local part	La partie avant @ est invalide.
hwid (email) has invalid domain part	La partie du domaine est invalide.
hwid (email) has disposable domain	L’adresse utilise un domaine d’e-mail jetable/temporaire (par ex. 10minutemail).
hwid is not valid	Le hwid lui-même est malformé.
only email platform allowed for Email Only subscription	Le compte est sur un plan E-mail Uniquement et ne peut pas enregistrer d’appareils non-email.

Note

Seuls les rebonds permanents (hard bounces) ajoutent une adresse à la liste noire. Les rebonds temporaires (soft bounces) et les plaintes pour spam ne bloquent pas registerEmail — seul this hwid (email) is blacklisted reflète la suppression.

deleteEmail

Supprime une adresse e-mail de votre base d’utilisateurs.

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

En-têtes de la requête

Nom	Requis	Valeur	Description
Authorization	Oui	Token XXXX	Jeton d’API d’Appareil pour accéder à l’API d’Appareil. Remplacez XXXX par votre jeton d’API d’Appareil réel.

Corps de la requête

Nom	Type	Description
application	string	Code d’application Pushwoosh
email	string	Adresse e-mail utilisée dans la requête /registerEmail.

200

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

Exemple

{
  "request": {
    "application": "APPLICATION_CODE",  // required. Pushwoosh application code
    "email": "email@domain.com"         // required. Email to delete from app subscribers.
  }
}

setEmailTags

Définit les valeurs de tag pour l’adresse e-mail.

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

En-têtes de la requête

Nom	Requis	Valeur	Description
Authorization	Oui	Token XXXX	Jeton d’API d’Appareil pour accéder à l’API d’Appareil. Remplacez XXXX par votre jeton d’API d’Appareil réel.

Corps de la requête

Nom	Type	Description
application	string	Code d’application Pushwoosh
email	string	Adresse e-mail.
tags	object	Objet JSON de tags à définir, envoyez ‘null’ pour supprimer la valeur.
userId	string	ID Utilisateur associé à l’adresse e-mail.

200

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

Exemple

{
  "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.
  }
}

Note

Pour les autres types d’appareils, un 200 OK sera retourné, bien que les tags ne soient pas sauvegardés.

Attention

Veuillez éviter de définir plus de 50 valeurs de tag dans une seule requête /setEmailTags.

registerEmailUser

Associe un ID Utilisateur externe à une adresse e-mail spécifiée.

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

Note

Veuillez noter que cette méthode n’enregistre pas une adresse e-mail dans votre base d’utilisateurs ; elle ne doit être utilisée que pour assigner des ID utilisateur à des adresses e-mail qui ont déjà été enregistrées par une requête /registerEmail.

Peut être utilisé dans l’appel API /createEmailMessage (le paramètre ‘users’).

En-têtes de la requête

Nom	Requis	Valeur	Description
Authorization	Oui	Token XXXX	Jeton d’API d’Appareil pour accéder à l’API d’Appareil. Remplacez XXXX par votre jeton d’API d’Appareil réel.

Corps de la requête

Nom	Type	Description
application*	string	Code d’application Pushwoosh
email*	string	Adresse e-mail.
userId*	string	ID Utilisateur à associer à l’adresse e-mail.
tz_offset	integer	Décalage de fuseau horaire en secondes.

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."
}

Exemple

{
  "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.
  }
}

Note

Pour récupérer des données sur les rebonds temporaires (soft bounces), les rebonds permanents (hard bounces) et les plaintes pour spam, y compris la date, l’adresse e-mail et la raison de chaque rebond, utilisez la méthode BouncedEmails.