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-mail du Panneau de Contrôle. Chaque modèle stocke les sujets par locale, 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 d’e-mail email_template) ou un point Envoyer un e-mail d’un 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 l’une ou l’autre casse. 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/parcours ci-dessus.
Champs non remplis : les réponses incluent tous les champs, même lorsqu’ils sont vides ou ont une valeur nulle.

Réponses d’erreur

Statut HTTP	Signification
`400 Bad Request`	Argument invalide — un champ obligatoire est manquant ou mal formé, ou une précondition a échoué (par exemple, la suppression d’un modèle encore utilisé par un parcours).
`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 retourne 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, de 1 à 255 caractères.
`content`	object	Oui	L’objet de contenu de l’e-mail.
`label`	string	Non	Étiquette de texte libre, jusqu’à 255 caractères.
`categories`	array of strings	Non	Noms de catégories pour étiqueter le modèle.
`previewSettings`	object	Non	Paramètres de prévisualisation de l’éditeur arbitraires, stockés et retournés tels quels.
`system`	boolean	Non	Marque le modèle comme un modèle système — une fonctionnalité interne, par ex. un fragment de bloc synchronisé. Les modèles système sont masqués de `List` (voir la note ci-dessous), mais restent accessibles par leur 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

Retourne { "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 retourné 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 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. Par défaut à `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 si `strictSearchByLabel` est `true`.
`strictSearchByLabel`	boolean	Non	Utiliser la correspondance exacte au lieu de la 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` pour chaque élément.
`page`	integer	L’index de la page retournée.
`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

Retourne un seul modèle d’e-mail par son code, y compris les informations sur l’expéditeur, les sujets par locale 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 requête

Paramètre	Type	Requis	Description
`includeHtml`	boolean	Non	Indique s’il faut retourner le `html` rendu avec le contenu de l’éditeur. La valeur par défaut est `true`. Mettez à `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

Retourne { "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, de 1 à 255 caractères. Omettre pour conserver le nom actuel.
`content`	object	Non	Nouvel objet de contenu de l’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é.

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

Retourne { "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 son 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 retourné 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, de 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 le `code` d’appel de `Get`/`Update`/`Delete`.

Référence d’objet

Les noms de champs ci-dessous correspondent à ce que Get, List, Update et Create retournent 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égories.
`content`	object	L’objet de contenu de l’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 de l’e-mail

Champ	Type	Description
`sender_info`	object	Objet d’informations sur l’expéditeur — adresses `from` et `reply_to`.
`subject`	object (map)	Sujet par locale, par ex. `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	Le contenu de l’éditeur. Exactement un de ceux-ci 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 d’Unlayer.
`pushwoosh`	`html`, `localization_data`	`localization_data`	L’éditeur HTML propre à Pushwoosh. Recommandé pour les modèles créés par programme/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 locale : un objet dont les clés sont les codes de locale (en, es, default, …), où chaque valeur est la copie des champs de l’éditeur pour cette locale. Sa structure interne est spécifique à l’éditeur et opaque pour cette API — l’API la stocke et la retourne telle quelle. Il est requis sur Create/Update pour chaque type (envoyez {} s’il n’y a rien à localiser).

Chaque fois que l’API retourne du content (actuellement seulement avec Get, puisque Create et Update ne le renvoient pas en écho), elle garantit qu’une locale 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 locale qui vient) en default, en la renommant — toutes les autres locales 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 locale 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 a disparu à partir de ce moment, de façon permanente. Si vous devez conserver la clé de locale originale, renommez vous-même default pour la rétablir avant d’appeler Update.

Le texte à l’intérieur de html ou d’une valeur de 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 retourne 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