Templates et variables

Enregistrez un message type une fois, puis remplissez ses variables à chaque envoi.

Forfait requis

Les templates d'email sont inclus dans les forfaits Pro et Agency (ainsi qu'Enterprise). Sur un autre forfait, le paramètre template répond 403 feature_not_available.

Le principe

Un template contient un sujet et un corps dans lesquels vous placez des variables entre accolades : {prenom}, {numero_commande}, {date}… À l'envoi, vous fournissez les valeurs et le service produit le message final.

Cela évite de dupliquer le texte de vos emails dans le code de chaque application, et permet de corriger une formulation sans redéployer.

1. Créer un template

Ouvrez Templates dans l'application et renseignez :

Champ	Description
Nom	Libellé lisible, affiché dans la liste.
Identifiant	Le slug passé à l'API dans le paramètre `template` (ex. `confirmation-commande`). Déduit du nom si vous le laissez vide.
Sujet	Peut contenir des variables.
Format	Texte brut ou HTML, utilisé par défaut à l'envoi.
Corps	Le message, avec ses variables.

Exemple de corps :

template texte

Sujet : Votre commande {numero_commande} est confirmée

Bonjour {prenom},

Nous avons bien reçu votre commande {numero_commande} du {date_commande}.
Montant total : {montant} €.

Livraison prévue le {date_livraison}.

À bientôt,
L'équipe {societe}

La liste des variables détectées est affichée à côté de chaque template : pratique pour vérifier qu'on n'en a pas oublié une.

2. L'utiliser depuis l'API

Passez l'identifiant du template dans template, et les valeurs dans vars (un objet JSON) :

bash

curl -X POST "https://mailer.echange.online/api/send.php" \
  -H "X-API-Key: VOTRE_CLE_API" \
  -d "template=confirmation-commande" \
  -d "to=alice@example.com" \
  -d "from=contact@mondomaine.com" \
  --data-urlencode 'vars={"prenom":"Alice","numero_commande":"CMD-1042","date_commande":"12/01/2026","montant":"89,90","date_livraison":"18/01/2026","societe":"Mon Domaine"}'

La même requête en JSON :

bash

curl -X POST "https://mailer.echange.online/api/send.php" \
  -H "X-API-Key: VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "confirmation-commande",
    "to": "alice@example.com",
    "from": "contact@mondomaine.com",
    "vars": {
      "prenom": "Alice",
      "numero_commande": "CMD-1042",
      "montant": "89,90"
    }
  }'

Règles de substitution

Une variable s'écrit {nom} : lettres, chiffres, _, - et ., 64 caractères maximum.
La substitution se fait en une seule passe : une valeur qui contiendrait {autre} n'est pas ré-interprétée.
Il n'y a ni boucle, ni condition, ni appel de fonction : un template ne peut pas exécuter de logique.
Une accolade qui n'encadre pas un nom valide est laissée telle quelle — votre CSS et votre JSON dans un corps HTML ne sont pas altérés.
Les variables du sujet et du corps sont remplies par le même objet vars.

Variables manquantes

Par défaut, oublier une valeur est une erreur : mieux vaut un appel refusé qu'un client qui reçoit « Bonjour {prenom} ».

json · HTTP 422

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Variables non fournies : {montant}, {date_livraison}. Fournissez-les dans \"vars\", ou passez strict_vars=0 pour les laisser telles quelles."
  }
}

Si vous voulez au contraire un remplissage partiel (les placeholders restants sont conservés dans le message), ajoutez strict_vars=0.

Templates HTML et sécurité

À savoir

Dans un template html, les valeurs fournies sont échappées avant insertion : une valeur contenant <script> apparaîtra comme du texte, pas comme une balise. Vous pouvez donc injecter sans risque des données saisies par vos utilisateurs. Corollaire : une variable ne peut pas servir à insérer du balisage — la mise en forme doit être dans le template lui-même.

Surcharger un template ponctuellement

Les paramètres explicites de la requête l'emportent sur le template. Utile pour un cas particulier sans créer un second modèle :

Paramètre fourni	Effet
`subject`	Remplace le sujet du template (les variables y sont aussi remplacées).
`body`	Remplace le corps du template.
`format`	Force le format d'envoi, quel que soit celui du template.

bash

# Même template, mais objet spécifique pour cette campagne
curl -X POST "https://mailer.echange.online/api/send.php" \
  -H "X-API-Key: VOTRE_CLE_API" \
  -d "template=confirmation-commande" \
  -d "to=alice@example.com" \
  -d "from=contact@mondomaine.com" \
  -d "subject=[URGENT] Votre commande {numero_commande}" \
  --data-urlencode 'vars={"prenom":"Alice","numero_commande":"CMD-1042"}'

Envoyer un lot personnalisé

Un envoi = un appel API. Pour écrire à cent clients avec un contenu personnalisé, bouclez côté application ; pensez à respecter votre limite de débit par minute (voir Quotas et limites).

php

<?php
$clients = [
    ['email' => 'alice@example.com', 'prenom' => 'Alice', 'commande' => 'CMD-1042'],
    ['email' => 'bob@example.com',   'prenom' => 'Bob',   'commande' => 'CMD-1043'],
];

foreach ($clients as $client) {
    $ch = curl_init('https://mailer.echange.online/api/send.php');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('MAIL_SENDER_KEY')],
        CURLOPT_POSTFIELDS => http_build_query([
            'template' => 'confirmation-commande',
            'to' => $client['email'],
            'from' => 'contact@mondomaine.com',
            'vars' => json_encode([
                'prenom' => $client['prenom'],
                'numero_commande' => $client['commande'],
            ], JSON_UNESCAPED_UNICODE),
        ]),
    ]);

    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 429) {
        sleep(60); // limite de débit atteinte : on patiente avant de reprendre
    }
}