Modèles

Un modèle est un document HTML complet accompagné d'un objet par défaut. Le rendu est le seul appel ici qui n'envoie jamais rien — utilisez-le aussi souvent que vous voulez.

Ce qu'est un modèle, en HTTP

Un modèle est un fichier HTML. Il n'y a aucune mise en page autour : ce que vous envoyez est ce que reçoivent les destinataires, ce qui veut aussi dire que le lien de désabonnement doit se trouver dans votre propre balisage — voir Aide-mémoire des balises de fusion.

Le catalogue de modèles

Écrire 150 lignes de HTML d'e-mail à la main, correctement, est une mauvaise façon d'employer le temps de quiconque — le vôtre ou celui d'un agent. Le catalogue est un petit ensemble de modèles que nous maintenons : ils portent leur lien de désabonnement, leurs zones modifiables, et ils ont été vérifiés sur les clients de messagerie qui comptent. Vous en lisez un, vous le copiez, vous modifiez votre copie. Lecture seule. Il n'existe aucun endpoint pour ajouter, modifier ou supprimer un modèle du catalogue : le catalogue appartient au produit, pas à une organisation. Il est le même pour toutes les clés. Seuls les modèles publiés sont visibles. Un brouillon répond 404, exactement comme un identifiant qui n'existe pas — impossible de distinguer les deux, et c'est voulu. Une clé d'API reste obligatoire, comme sur chaque route /api/v1. Elle ne sert ici à rien filtrer : le catalogue est commun à toutes les organisations, il n'y a donc rien à restreindre.

Créer un modèle à partir du catalogue

POST /api/v1/templates prend galleryTemplateId à la place de content. Le serveur lit le modèle publié et copie son HTML, si bien que vous ne faites jamais transiter 150 lignes par votre propre processus.
ChampOùObligatoireDescription
namecorpsouiDe 1 à 100 caractères
galleryTemplateIdcorpsoui*Le modèle du catalogue à copier. Remplace content
defaultSubjectcorpsnonReprend l'objet du modèle du catalogue si vous l'omettez
* Soit galleryTemplateId, soit content — voir ci-dessous.
bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name": "August newsletter", "galleryTemplateId": "'"$GALLERY_TEMPLATE_ID"'"}' \
  "https://www.agentsmail.io/api/v1/templates"
C'est une copie, pas un héritage. Votre modèle détient son propre HTML dès sa création. Améliorez le modèle du catalogue demain, et rien du vôtre ne change ; modifiez votre modèle, et le catalogue n'est pas touché. Plus rien ne les relie ensuite — il n'existe pas d'endpoint « mettre à jour depuis le modèle », et nous n'avons aucun moyen de changer ce que vous avez déjà.
ConditionRéponse
galleryTemplateId seul201 — le HTML du modèle du catalogue est copié
content seul201 — votre HTML, balises de fusion converties
les deux ensemble400 — deux documents différents, choisissez-en un
aucun des deux400 — un modèle a besoin d'un document
galleryTemplateId inconnu, ou non publié400 — le message nomme le paramètre
Envoyer les deux est refusé exprès. Une priorité silencieuse enverrait un HTML que vous n'avez pas choisi, et vous le découvririez quand l'e-mail arriverait dans une boîte de réception. Le modèle créé de cette façon est à vous comme n'importe quel autre : même organisation que la clé, mêmes validations, mêmes limites. Le HTML du modèle du catalogue est copié octet pour octet — aucune conversion ne s'y applique, donc ce que nous avons publié est exactement ce que vous obtenez. Comme rien n'est converti, toute balise de fusion Mailchimp encore présente dans ce HTML revient dans unsupportedTags, y compris celles que nous traduirions autrement : elles sont restées brutes dans votre document et ne seront pas interprétées au rendu de l'e-mail. Les modèles du catalogue sont normalement écrits dans notre propre vocabulaire {{...}}, donc cette liste est généralement vide — mais on vous prévient quand elle ne l'est pas, plutôt que de vous laisser le découvrir dans une boîte de réception.