Faire le rendu sans envoyer

POST /api/v1/render Fait le rendu d'un e-mail avec des données d'exemple et renvoie le résultat. Il n'envoie rien, ne stocke rien et ne change rien — c'est le seul endpoint ici sans aucun effet de bord, alors appelez-le aussi souvent que vous voulez, avant et après chaque modification. unsubscribeUrl, today, currentYear et poweredBy ne sont pas des valeurs d'exemple : le serveur les calcule et remplace tout ce que vous envoyez pour eux. La date et l'année proviennent du fuseau horaire et de la langue réglés sur l'organisation de la clé d'API, ni de l'appelant ni de l'horloge du serveur — si bien qu'un rendu répond avec la même date que celle que lira le destinataire. L'un de templateId ou content est obligatoire — n'envoyer ni l'un ni l'autre répond 400. Envoyer les deux fait le rendu de votre content avec l'objet du modèle, c'est ainsi que vous essayez une modification avant de l'enregistrer.
json
{
  "success": true,
  "data": {
    "html": "<html>…<p>Hi Camille</p>…</html>",
    "text": "Hi Camille …",
    "subject": "What shipped in August",
    "unknownVariables": ["company"]
  }
}
unknownVariables liste les emplacements {{…}} qui ne font pas partie du vocabulaire. Ils se résolvent en chaîne vide à l'envoi — rien ne casse, mais rien ne s'affiche non plus. Corrigez-les ici.
Un HTML sans lien de désabonnement est refusé, ici comme à l'envoi. La réponse est un 400 qui nomme le problème : ajoutez {{unsubscribeUrl}} dans un lien de votre HTML. Rien n'est jamais ajouté à votre balisage à votre place, si bien qu'un modèle dont le rendu passe est un modèle qui peut être envoyé.
Le lien de désabonnement utilisé pendant le rendu est une URL d'exemple : un rendu n'a pas de destinataire, donc pas de vrai jeton de désabonnement. Il est là pour prouver que le lien existe, pas pour fonctionner.

Autorisation

Rôle dans l'organisationCet endpoint
OWNERAutorisé
ADMINAutorisé
MEMBERAutorisé
Une clé porte le rôle que son créateur détient dans cette organisation — jamais un rôle sur AgentsMail lui-même. Voir Clés d'API.

Corps de la requête

ChampTypeObligatoireDescription
templateIdstringnonFait le rendu d'un modèle de votre organisation
contentstringnonFait le rendu d'un HTML brut — l'emporte sur le contenu propre du modèle
subjectstringnonVaut par défaut le defaultSubject du modèle
previewTextstring | nullnonJusqu'à 200 caractères après suppression des espaces en début et fin. Rendu à l'emplacement de {{previewText}} ou {{preheader}} ; absent, vide ou null, il est rendu vide
preheaderstring | nullnonAlias compatible de previewText ; des valeurs normalisées différentes renvoient 400
variablesobjectnonValeurs d'exemple : firstName, lastName, email
json
{
  "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.",
  "content": "<div data-skip-in-text=\"true\" style=\"display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden;mso-hide:all;\">{{previewText}}</div><p>Hello</p><a href=\"{{unsubscribeUrl}}\">Unsubscribe</a>"
}

Exemple

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"templateId":"'$TEMPLATE_ID'","variables":{"firstName":"Camille"}}' \
  "https://www.agentsmail.io/api/v1/render"

Réponse

  • 200 OK — l'e-mail rendu.
  • 400 Bad Request — champs invalides, alias d'aperçu contradictoires, ou HTML obligatoire manquant.
  • 401 Unauthorized — clé absente ou invalide, ou son propriétaire a quitté l'organisation.
  • 429 Too Many Requests — plus de 120 requêtes en une minute pour cette clé.

Champs de la réponse

ChampTypeDescription
successbooleanIndique si l'opération a réussi
data.htmlstringLe document rendu, balises de fusion résolues
data.textstringSon équivalent en texte brut
data.subjectstringL'objet après résolution
data.unknownVariablesstring[]Balises que le produit ne connaît pas — laissées visibles dans le résultat
data.warningsstring[]missing_postal_address, dark_mode_contrast_corrected, dark_mode_contrast_unverified, dark_mode_declaration_removed, missing_preheader_shortcode

Exemple de réponse

json
{
  "success": true,
  "data": {
    "html": "<html>…</html>",
    "text": "August news…",
    "subject": "August news",
    "unknownVariables": [],
    "warnings": []
  }
}

Recette pour agent

Le rendu est le seul appel sans effet de bord : bouclez dessus jusqu'à ce que le document soit propre, puis créez la campagne. Un agent qui saute cette étape envoie {{fistName}} dans de vraies boîtes de réception.
js
const render = async (content) =>
  (
    await fetch(`${base}/render`, {
      method: 'POST',
      headers: {...headers, 'content-type': 'application/json'},
      body: JSON.stringify({content}),
    })
  ).json()

let html = draft
for (let attempt = 0; attempt < 3; attempt++) {
  const {data} = await render(html)
  if (data.unknownVariables.length === 0) break
  html = fixTypos(html, data.unknownVariables) // your own correction pass
}

Remarques

previewText et preheader désignent la même valeur. Si les deux sont fournis, ils doivent être identiques après suppression des espaces en début et fin (null compris). Une valeur non vide sans aucun des deux shortcodes en dehors des commentaires HTML renvoie missing_preheader_shortcode. Rien n'est inséré dans le HTML.

Voir aussi