Utiliser les champs et les conditions dans les modèles de courriel HTML

Les modèles de courriel HTML Payreq peuvent combiner du HTML fixe avec des valeurs ajoutées lorsqu’un courriel est généré. Ils peuvent également afficher ou masquer des sections en fonction de la facture, des exigences de paiement, des liens disponibles et du statut de paiement automatique du destinataire.

Cet article est destiné aux mailhouses et aux Contacts techniques qui créent, fournissent ou maintiennent leur propre code HTML. Il explique la syntaxe du modèle disponible, d’où proviennent les valeurs et quels champs dépendent de la configuration Payreq de l’expéditeur.

Pour les paramètres de compte qui sélectionnent le modèle et contrôlent sa formulation standard, voir Paramètres des canaux de livraison.

Avant de commencer

Payreq permet de sélectionner le HTML des courriels de deux façons :

• Un modèle stocké, sélectionné dans les paramètres du canal de courriel.
• Un fichier HTML fourni pour une facture dans un chargement SFTP.

Ne présumez pas que les deux méthodes prennent en charge des substitutions identiques. La disponibilité des champs peut dépendre du type de modèle, du compte de l’expéditeur, de la configuration du compte et du mappage des factures. Confirmez ces détails avant d’utiliser un champ en production.

Les paramètres des canaux de livraison s’appliquent à un compte Payreq Delivery. Si votre organisation dispose de plusieurs comptes Delivery, confirmez les paramètres de chaque compte séparément. Si vous ne savez pas quels paramètres ou mappages s’appliquent, contactez Payreq Support pour obtenir de l’aide.

Syntaxe du modèle

Les modèles Payreq utilisent des champs et des sections de style Mustache. Les noms de champs, la ponctuation et les points d’interrogation doivent correspondre exactement.

Utilisez l’esperluette uniquement lorsque le champ est documenté avec ce symbole. Elle permet une sortie sans échappement; ne l’ajoutez pas par défaut aux champs de texte.

D’où proviennent les valeurs du modèle

Les valeurs des modèles se répartissent en plusieurs groupes pratiques :

Une valeur au niveau du compte n’est pas nécessairement codée en dur. Par exemple, {{email-from}} est inséré lors de la génération du courriel, mais sa source est la configuration du canal Courriel du compte.

Champs du canal Courriel

Les champs suivants correspondent aux paramètres du canal de courriel. Les noms des paramètres sont indiqués en anglais pour correspondre à l’illustration et éviter de les confondre avec les champs de modèle :

Email as Text et l’objet du courriel

Le paramètre Email as Text est utilisé pour construire l’objet par défaut. Voici un exemple de structure :

[Email Notice Type Text] [Email as Text] [biller name]

Par exemple, si les valeurs sont Rates notice, from et Riverstone City Council, le sujet résultant est :

Rates notice from Riverstone City Council

Email as Text concerne l’objet du courriel; ce n’est pas un champ du corps du message. Communiquez avec le soutien Payreq si votre configuration exige un comportement différent pour l’objet ou le corps.

Les éléments suivants sont également distincts :

• {{email-from}}, ​​qui insère le libellé configuré dans le corps ;
• le nom d’affichage et l’adresse dans l’en-tête De du courriel ; et
• l’adresse Réponse.

N’utilisez pas Email from Text pour changer l’expéditeur dans l’en-tête du courriel.

Champs de compte et de marque

Utilisez haslogo autour de l’élément d’image complet afin qu’une image vide ne soit pas laissée lorsqu’aucun logo n’est disponible :

{{#haslogo}}
  <img src="{{logo-bytes}}" alt="{{biller-name}} logo">
{{/haslogo}}

Champs de facturation et de client

Références de facture numérotées

Les champs bill-ref reprennent les champs de référence de la facture dans l’ordre : bill-ref-1 lit le premier, bill-ref-2 le deuxième, et ainsi de suite. Leur signification dépend du mappage de votre intégration. Confirmez-la pour votre compte plutôt que de reprendre celle d’un autre expéditeur. Une position non renseignée produit une valeur vide.

Avant d’utiliser une référence numérotée :

1. Vérifiez l’interface de l’expéditeur et le mappage d’intégration.
2. Attribuez à chaque champ source une valeur de test unique.
3. Générez un courriel de test en utilisant le compte et le type de modèle prévus.
4. Confirmez que le HTML reçu contient la valeur attendue à la position attendue.

Ne copiez pas les significations des références à partir du modèle d’un autre expéditeur.

Conditions de paiement et contenu du montant

Les champs conditionnels permettent à un modèle de couvrir différents états de facture et de paiement.

no-payment-override et amount-zero-or-below? testent différentes choses. Une facture peut avoir un montant dû nul ou négatif tout en étant marquée comme nécessitant un paiement. Testez-les séparément lorsque la formulation ou les actions dépendent des deux états.

pay-now-button? est un résultat calculé. Cela peut être faux parce que le paiement n’est pas requis ou parce qu’un accord de paiement automatique est déjà actif. Ne le traitez pas comme une copie directe de la valeur de paiement requis de la facture.

Sections positives et inversées

Cet exemple montre une formulation différente selon l’exigence de paiement explicite :

{{^no-payment-override}}
  <p>Amount due: {{&amount}}</p>
  <p>Due date: {{due-date}}</p>
{{/no-payment-override}}

{{#no-payment-override}}
  <p>No payment is required.</p>
{{/no-payment-override}}

Les noms d’ouverture et de fermeture doivent correspondre exactement. Par exemple, ouvrez et fermez pay-now-button? avec le point d’interrogation inclus dans les deux balises.

Valeurs de paiement automatique

Ces champs peuvent être utilisés dans une section auto-payment? :

Le comportement de auto-payment.min-amount-payable? dépend de la configuration de paiement de l’expéditeur. Demandez à Payreq Support de confirmer la règle applicable avant d’ajouter un libellé qui dépend de cette condition.

Liens générés par Payreq

Utilisez haslink sur toute la section du lien ou de l’appel à l’action. Cela empêche qu’un href vide apparaisse là où un lien de facture n’est pas disponible.

Contenu HTML statique

Payreq ne remplace pas le HTML ordinaire. Le libellé et les ressources sans champs de modèle restent les mêmes pour chaque courriel utilisant ce modèle.

Examinez le contenu statique séparément, notamment :

• les coordonnées de l’organisation ;
• les libellés de paiement et les politiques ;
• des liens vers des sites Web externes ;
• les URL des images hébergées et des badges d’application ;
• unités ajoutées aux valeurs, telles que kL ; et
• notes de bas de page juridiques et texte d’accessibilité.

JavaScript ne doit pas être utilisé pour calculer ou remplacer le contenu des courriels. La plupart des clients de messagerie bloquent ou suppriment les scripts. Utilisez plutôt des champs de modèle, des sections conditionnelles et du HTML sécurisé pour les courriels.

Utilisez des URL HTTPS complètes pour les liens et les images hébergées. Utilisez le CSS en ligne pour les présentations importantes, car les clients de messagerie offrent une prise en charge limitée et incohérente des feuilles de style.

Fournir du HTML dans un chargement de document SFTP

Pour fournir un fichier HTML pour chaque facture, le canal de courriel Type de modèle doit être défini sur Fourni lors du chargement du document SFTP. Chaque nom de fichier HTML doit correspondre au fichier nommé dans le champ Détails de livraison par courriel de cette facture, et le fichier HTML doit être inclus dans le package de facture.

La valeur Email Delivery Details est un objet JSON dont les clés indiquent la langue. Par exemple :

{
  "en": {
    "subject": "Your rates notice is available",
    "reply-to": "rates@example.com",
    "html-file": "invoice_INV10432.html",
    "add-attachment": true
  }
}

Payreq détermine le destinataire à partir de l’inscription du client. Reportez-vous à la Spécification de l’interface Payreq actuelle pour connaître le format de champ complet, les règles de langue, les exigences en matière de nom de fichier et le comportement de l’expéditeur.

Les images et autres ressources référencées par le HTML fourni dans le chargement doivent être hébergées par le Mailhouse. Ne référencez pas de fichiers locaux du lot HTML, sauf si la Spécification de l’interface autorise explicitement ce fonctionnement.

Dans la configuration vérifiée, les cinq champs des paramètres du canal de courriel, y compris la couleur de marque, ainsi que les champs de facture et de référence, ont été remplacés de la même façon dans un modèle stocké et dans le HTML fourni avec le chargement. Le courriel reçu ne contenait aucune syntaxe de modèle non résolue, et le PDF fourni était joint. Payreq remplace toutefois le nom de fichier fourni par un nom généré. Confirmez toujours le mappage et le type de modèle de votre propre compte.

Champs nécessitant une confirmation spécifique à l’expéditeur

Confirmez-les avant de vous y fier dans un nouveau modèle de production :

Un résultat vide ne prouve pas qu’un champ n’est pas pris en charge. Cela peut signifier que le champ source n’a pas été renseigné, que le mappage de l’expéditeur ne l’expose pas, que le champ n’est pas disponible dans ce chemin de modèle ou que le nom du champ est incorrect.

Vérifier un modèle avant la production

Utilisez des valeurs synthétiques et des destinataires internes contrôlés. Pour chaque essai :

1. Enregistrez le compte de livraison, les paramètres du canal Courriel, le type de modèle, le nom du modèle, l’ID de tâche ou de chargement et le destinataire du test.
2. Donnez à chaque champ source une valeur distincte afin que son origine soit claire.
3. Incluez les factures qui exercent les branches positives et inversées que vous utilisez.
4. Enregistrez le .eml reçu ou la source du message brut, pas seulement une capture d’écran.
5. Vérifiez séparément le sujet, le nom d’expéditeur affiché, l’adresse de réponse, le corps visible, le code HTML brut et les destinations des liens.
6. Testez les clients de messagerie que vos destinataires utilisent couramment.
7. Restaurez tous les paramètres de compte modifiés pour le test.
8. Envoyez un courriel de contrôle final avant d’utiliser le modèle pour une exécution de facture en direct.

Contactez Payreq Support si la source, le mappage ou la règle conditionnelle d’un champ ne peut pas être confirmé en toute sécurité dans un compte test.

Articles connexes

• Paramètres des canaux de livraison
• Spécification de l’interface Payreq
• Canaux d’Abonnement disponibles dans Payreq Delivery