API des modèles d'e-mail

L’API des modèles d’e-mail gère les modèles d’e-mail réutilisables derrière les préréglages d’e-mail d’une application — les mêmes modèles que vous construisez dans l’éditeur d’e-mails du Control Panel. Chaque modèle stocke les objets par langue, les informations sur l’expéditeur et le contenu de l’éditeur, et est identifié par le code du préréglage d’e-mail auquel il est connecté. Utilisez ce code pour envoyer le modèle via Notify (charge utile de l’e-mail email_template) ou un point Envoyer un e-mail de Customer Journey.

URL de base

https://rpc-api.svc-nue.pushwoosh.com

Tous les points de terminaison sont servis via HTTPS. Les requêtes et les réponses utilisent application/json sauf indication contraire.

Authentification

Chaque requête doit inclure un en-tête Authorization avec votre jeton d’API serveur :

Authorization: Api VOTRE_JETON_API

Conventions

Nommage des champs : les corps de requête et les paramètres de requête/chemin acceptent le lowerCamelCase (par exemple, previewSettings, searchByLabel, includeHtml) — le serveur désérialise les deux casses. Les réponses sont toujours sérialisées en utilisant les noms de champs proto, en snake_case (per_page, email_template, sender_info, preview_settings, etc.). Les exemples de réponse et la référence d’objet ci-dessous utilisent cette casse.
code : chaque réponse de modèle contient le code de son préréglage d’e-mail connecté, et non un ID de modèle interne. Transmettez ce même code à Get, Update, Delete, et aux API de messagerie/journey ci-dessus.
Champs non remplis : les réponses incluent tous les champs, même lorsqu’ils sont vides ou nuls.

Réponses d’erreur

Statut HTTP	Signification
`400 Bad Request`	Argument invalide — un champ obligatoire est manquant ou malformé, ou une précondition a échoué (par exemple, la suppression d’un modèle encore utilisé par un journey).
`401 Unauthorized`	En-tête `Authorization` manquant ou invalide.
`403 Forbidden`	L’application ou le préréglage n’appartient pas au compte de l’appelant.
`404 Not Found`	Le modèle, le préréglage ou l’application n’a pas été trouvé.
`500 Internal Server Error`	Échec inattendu côté serveur.

Points de terminaison

Méthode	Chemin	Description
`POST`	`/api/email_templates`	Créer un nouveau modèle d’e-mail
`GET`	`/api/email_templates`	Lister les modèles d’e-mail d’une application
`GET`	`/api/email_templates/{code}`	Obtenir un seul modèle d’e-mail
`PUT`	`/api/email_templates/{code}`	Mettre à jour un modèle d’e-mail
`DELETE`	`/api/email_templates/{code}`	Supprimer un modèle d’e-mail
`POST`	`/api/email_templates:clone`	Cloner un modèle d’e-mail dans une application

Créer

Crée un nouveau modèle d’e-mail — son contenu d’éditeur plus un préréglage d’e-mail connecté — dans une application, et renvoie le code de modèle généré.

POST /api/email_templates

Corps de la requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application Pushwoosh dans lequel créer le modèle.
`name`	string	Oui	Nom du modèle, 1 à 255 caractères.
`content`	object	Oui	L’objet de contenu d’e-mail.
`label`	string	Non	Étiquette de texte libre, jusqu’à 255 caractères.
`categories`	array of strings	Non	Noms de catégorie pour étiqueter le modèle.
`previewSettings`	object	Non	Paramètres de prévisualisation de l’éditeur arbitraires, stockés et renvoyés tels quels.
`system`	boolean	Non	Marque le modèle comme un modèle système — une fonctionnalité interne, par exemple un fragment de bloc synchronisé. Les modèles système sont masqués de `List` (voir la note ci-dessous), mais restent accessibles par code. La valeur par défaut est `false`.

Exemple de requête

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

Réponse

Renvoie { "email_template": { ... } } — l’objet de modèle d’e-mail créé, mais sans content (ce point de terminaison ne le renvoie pas en écho). Appelez Get avec le code renvoyé si vous avez besoin de relire le contenu.

Lister

Liste les modèles d’e-mail d’une application — métadonnées uniquement, pas de contenu — avec pagination, tri et filtrage par nom, étiquette ou catégorie.

GET /api/email_templates

Paramètres de la requête

Paramètre	Type	Requis	Description
`application`	string	Oui	Le code d’application pour lequel lister les modèles.
`orderBy`	string	Non	`NAME` (par défaut), `CREATED` ou `UPDATED`.
`orderDirection`	string	Non	`ASC` (par défaut) ou `DESC`.
`page`	integer	Non	Index de page basé sur zéro.
`perPage`	integer	Non	Taille de la page. La valeur par défaut est `100` si omis ou `0`. Ce point de terminaison n’impose pas de maximum explicite.
`searchByName`	string	Non	Correspondance de sous-chaîne (`like %value%`) avec le nom du modèle ou son code — l’une ou l’autre correspondance suffit.
`searchByLabel`	string	Non	Correspondance de sous-chaîne sur l’étiquette (`like %label%`), ou correspondance exacte lorsque `strictSearchByLabel` est `true`.
`strictSearchByLabel`	boolean	Non	Utiliser une correspondance exacte au lieu d’une sous-chaîne pour `searchByLabel`.
`searchByCategory`	array of strings	Non	Répétez le paramètre pour filtrer par plusieurs catégories, par ex. `?searchByCategory=lifecycle&searchByCategory=promo`.

Réponse

Champ	Type	Description
`email_templates`	array of objects	La page actuelle des objets de modèle d’e-mail. `content` est `null` sur chaque élément.
`page`	integer	L’index de page renvoyé.
`per_page`	integer	La taille de page utilisée pour cette réponse.
`total`	integer	Nombre total de modèles correspondant aux filtres, sur toutes les pages.

Exemple de réponse

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Obtenir

Renvoie un seul modèle d’e-mail par son code, y compris les informations sur l’expéditeur, les objets par langue et le contenu complet de l’éditeur.

GET /api/email_templates/{code}

Paramètres de chemin

Paramètre	Type	Description
`code`	string	Le code du modèle (le code de son préréglage d’e-mail connecté).

Paramètres de la requête

Paramètre	Type	Requis	Description
`includeHtml`	boolean	Non	Indique s’il faut renvoyer le `html` rendu avec le contenu de l’éditeur. La valeur par défaut est `true`. Réglez sur `false` pour l’ignorer — il représente généralement plus de la moitié de la charge utile, et le contenu de l’éditeur décrit déjà le modèle.

Réponse

Renvoie { "email_template": { ... } }, l’objet de modèle d’e-mail complet.

Mettre à jour

Met à jour un modèle d’e-mail existant par son code, en écrasant les champs fournis.

PUT /api/email_templates/{code}

Paramètres de chemin

Paramètre	Type	Description
`code`	string	Le code du modèle à mettre à jour.

Corps de la requête

Paramètre	Type	Requis	Description
`name`	string	Non	Nouveau nom, 1 à 255 caractères. Omettre pour conserver le nom actuel.
`content`	object	Non	Nouvel objet de contenu d’e-mail, remplaçant entièrement le contenu stocké. Omettre pour laisser le contenu inchangé.
`label`	string	Non	Nouvelle étiquette. Toujours écrasée — omettre ou envoyer `""` pour l’effacer.
`categories`	array of strings	Non	Nouvel ensemble complet de noms de catégories. Omettre pour laisser les catégories inchangées ; envoyer `[]` pour les effacer.
`previewSettings`	object	Non	Nouveaux paramètres de prévisualisation. Omettre pour laisser inchangés.

Exemple de requête

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

Réponse

Renvoie { "email_template": { ... } } — l’objet de modèle d’e-mail mis à jour, également sans content. Appelez Get si vous avez besoin de relire le contenu.

Supprimer

Supprime un modèle d’e-mail et son préréglage connecté par code, en supprimant le contenu stocké.

DELETE /api/email_templates/{code}

Paramètres de chemin

Paramètre	Type	Description
`code`	string	Le code du modèle à supprimer.

Réponse

Un objet vide en cas de succès : {}.

Cloner

Clone un modèle d’e-mail — son contenu et son préréglage — dans une application de destination, éventuellement sous un nouveau nom.

POST /api/email_templates:clone

Corps de la requête

Paramètre	Type	Requis	Description
`emailPresetCode`	string	Oui	Le `code` du modèle (tel que renvoyé par `Create`, `Get`, `List` ou `Update`) à cloner. Nommé `emailPresetCode` ici car c’est le code du préréglage d’e-mail connecté — voir les Conventions.
`application`	string	Oui	Code de l’application de destination. Peut être la même application, ou une autre appartenant au même compte.
`name`	string	Non	Nom pour le clone, 1 à 255 caractères. Par défaut, le nom du modèle source.

Exemple de requête

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

Réponse

Champ	Type	Description
`email_preset_code`	string	Le `code` du nouveau modèle — le même identifiant que celui utilisé par les appels `Get`/`Update`/`Delete`.

Référence d’objet

Les noms de champs ci-dessous correspondent à ce que Get, List, Update et Create renvoient réellement — les noms de champs proto en snake_case (voir les Conventions). Lorsque vous renvoyez ces mêmes structures dans un corps de requête (Create, Update), la forme lowerCamelCase utilisée dans les exemples de requête ci-dessus fonctionne également ; le serveur accepte l’une ou l’autre casse en entrée.

Objet de modèle d’e-mail

Champ	Type	Description
`code`	string	Code du préréglage d’e-mail connecté. Identifie ce modèle partout ailleurs dans l’API.
`name`	string	Nom du modèle.
`label`	string	Étiquette de texte libre.
`categories`	array of strings	Noms de catégorie.
`content`	object	L’objet de contenu d’e-mail. Rempli uniquement par `Get` ; `null` dans les réponses de `Create`, `List` et `Update`.
`preview_settings`	object	Paramètres de prévisualisation de l’éditeur arbitraires.
`created`	string (RFC 3339)	Horodatage de création.
`updated`	string (RFC 3339)	Horodatage de la dernière mise à jour.

Objet de contenu d’e-mail

Champ	Type	Description
`sender_info`	object	Objet d’informations sur l’expéditeur — adresses `from` et `reply_to`.
`subject`	object (map)	Objet par langue, par ex. `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	Le contenu de l’éditeur. Exactement un de ces éléments doit être défini — il sélectionne quel éditeur a produit (et rendra) le modèle. Voir les types d’éditeurs ci-dessous.

Types d’éditeurs

Type	Champ	Sous-champs requis	Description
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	Éditeur de blocs par glisser-déposer (Unlayer). `editor_config` est le JSON de conception Unlayer.
`pushwoosh`	`html`, `localization_data`	`localization_data`	L’éditeur HTML propre à Pushwoosh. Recommandé pour les modèles créés par programmation/API.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Éditeur de blocs Smart Cards ; `content` est son JSON spécifique à l’éditeur.

Dans chaque type, html est le rendu final. localization_data est le contenu propre à cet éditeur pour chaque langue : un objet indexé par code de langue (en, es, default, …), où chaque valeur est la copie des champs de l’éditeur pour cette langue. Sa structure interne est spécifique à l’éditeur et opaque pour cette API — l’API la stocke et la renvoie telle quelle. Elle est requise sur Create/Update pour chaque type (envoyez {} s’il n’y a rien à localiser).

Chaque fois que l’API renvoie du content (actuellement seulement avec Get, puisque Create et Update ne le renvoient pas en écho), elle garantit qu’une langue est exposée comme default : si vous n’avez pas envoyé de clé default vous-même, elle promeut en (ou, à défaut, la première clé de langue qui apparaît) en default, en la renommant — toutes les autres langues que vous avez envoyées sont conservées telles quelles. subject reçoit le même traitement. C’est différent de Clone, qui ne conserve que cette seule valeur de langue par défaut et supprime les autres.

Ce renommage n’est appliqué que lors de la construction de la réponse — mais il n’est pas annulé à l’écriture. Si vous prenez une réponse de Get telle quelle et l’envoyez directement à Update, la clé promue (par ex. en) est maintenant littéralement default, et Update stocke exactement ce que vous envoyez : la clé en originale est alors définitivement perdue. Si vous devez conserver la clé de langue originale, renommez vous-même default avant d’appeler Update.

Le texte à l’intérieur de html ou d’une valeur localization_data peut inclure des balises de Contenu Dynamique, par ex. {name|string|there} — celles-ci sont résolues par rapport aux Tags de l’appareil du destinataire lorsque l’e-mail est réellement envoyé. Cette API ne les résout pas ; elle stocke et renvoie simplement le texte que vous y mettez.

Objet d’informations sur l’expéditeur

Champ	Type	Description
`from`	object	`{ "email": string, "name": string }` — adresse de l’expéditeur.
`reply_to`	object	`{ "email": string, "name": string }` — adresse de réponse.

Les deux sous-champs email, lorsqu’ils ne sont pas vides, doivent être des adresses e-mail valides.

Sujets connexes

Notify

Référence de la charge utile de l'e-mail

Référence des points de Customer Journey