Documentation détaillée
Généralités
Authentification
Étapes de création d'un envoi e-mail
Étapes de création d'un envoi SMS
Nouveautés
administration du compte
contacts
abonnements
consentements
groupes d'intérêts
intérêts
champs
imports - mapping
imports de contacts
variables
ciblages
lois ciblages
critères ciblages
plannings
e-mail - adresses d'expéditeurs
e-mail - adresses de réponses
e-mail - liens de messages
e-mail - messages
e-mail - A/B test
sms - expéditeurs
sms - messages
sms - envois
sms - envois transactionnels
exports - mappings
exports - colonnes
exports - filtres
exports
statistiques
hébergement
webhooks
connexions distantes
consentements - dépréciées
imports de contacts - dépréciées
Powered by Stoplight
post

/email/sendings/transactional

Crée un envoi e-mail transactionnel immédiat ou différé, pour un destinataire unique présent ou pas dans votre base de contacts.

Par défaut, l’option des envois transactionnels n’est pas activée sur les comptes Campaign. Rapprochez-vous de votre référent commercial pour demander son activation et la mise en place d’un sous-domaine dédié à ces envois.

Un envoi e-mail transactionnel est constitué des 6 éléments suivants :

  • 1 type d’envoi (*) : TransactionalMarketing pour une communication à but marketing (recommandations produits, offres promotionnelles etc.) ou TransactionalService pour un envoi de service (renouvellement de mot de passe, e-mail de bienvenue etc.)
  • 1 contact (*) constitué par :
    • les champs de la clé d’unicité (*) du compte (souvent l’e-mail) pour identifier le contact (voir “exemple simple” dans la section Request Body ci-dessous). Si le contact n’existe pas, il sera créé automatiquement dans la base de contacts mais non accessible via le moteur de recherche s’il a fait seulement l’objet d’envois transactionnels de service TransactionalService.
    • les champs optionnels de la base de contacts utilisés pour la personnalisation des messages (voir “exemple avec personnalisation” dans la section Request Body ci-dessous). Si le contact est présent dans la base, ses informations seront mises à jour, sinon elles seront ajoutées.
  • les propriétés du message constituées par :
    • Name (*) : le nom du message (256 caractères maximum, éviter les noms de messages avec des caractères accentués). S’il n’est pas existant sur votre compte, il sera créé automatiquement avec l’ensemble des autres propriétés du message. S’il est déjà présent, ses propriétés existantes seront récupérées par défaut.
    • Subject (*) : l’objet de votre message e-mail.
    • CultureName : la langue du message (exemple : fr-FR ou en-EN etc.).
    • SenderID (*) : l’identifiant de l’adresse d’expéditeur du message (sélectionner une adresse d’expéditeur rattachée au sous-domaine dédié aux envois transactionnels).
    • ReplyAddressID : l’identifiant de l’adresse de réponse.
    • Format : le format du message (exemple : html ou text).
    • Editor : pour identifier l’éditeur utilisé pour générer le code HTML (exemple : Unknown ou Source ou Wysiwyg ou DolistGMR, Welkom).
    • DisableOpenTracking : désactivation du tracking d’ouverture (True/False).
    • ForceHttp : force le tracking http non sécurisé (True/False).
    • IsTrackingValidated : est-ce que le tracking de ce message est validé ? (True/False). Passez la valeur True pour un envoi transactionnel.
  • le contenu du message MessageContent qui se décompose en 3 éléments :
    • SourceCode (*) : le contenu HTML ou texte du message (voir “exemple avec création d’un message” dans la section Request Body ci-dessous).
    • EncodingType le type d’encodage (UTF8, Latin1, Latin2, Latin3, Latin4, Cyrillic, Arabic, Greek, Hebrew, Latin5, Latin7, Latin9, Unknown).
    • EnableTrackingDetection : booléen pour l’activation du tracking personnalisé des liens des messages utilisés lors des précédents envois (True/False).
  • Date et heure de planification de l’envoi : ScheduleDate au format ISO 8601. Vous pouvez décaler un envoi transactionnel jusqu’à maximum J+3 aprés l’appel à cette méthode. Si ScheduleDate n’est pas passé en entrée de cette méthode, l’envoi transactionnel sera déclenché immédiatement.
  • Le consentement facultatif du contact valable pour son inscription à l’abonnement global e-mail en renseignant les propriétés :
    • Purpose (*) : le texte que le contact a accepté correspondant à la finalité de traitement (au sens RGPD).
    • Date (*) : la date et l’heure du consentement au format ISO 8601. dd/MM/yyyy HH:mm:ss , dd-MM-yyyy HH:mm:ss, dd.MM.yyyy HH:mm:ss,MM-dd-yyyy HH:mm:ss, MM/dd/yyyy HH:mm:ss, MMddyyyy HH:mm:ss, MM.dd.yyyy HH:mm:ss, yyyy-MM-dd HH:mm:ss.
    • Origin (*) : origine physique comme l’IP du poste informatique avec laquelle le contact a donné son consentement.

(*) : paramètres obligatoires et nécessaires à l’envoi transactionnel

L’API permet différents usages :

  • envoyer un message existant : utiliser un message préalablement paramétré sur la plateforme. Si tous les paramètres obligatoires (*) sont déjà renseignés dans le message, vous pouvez générer l’envoi en spécifiant seulement le nom du message.
  • envoyer un message existant et surcharger ses propriétés : utiliser  un message préalablement paramétré sur la plateforme en renseignant le nom du message et ajoutez les propriétés que vous souhaitez surcharger (objet, expéditeur, HTML etc.).
  • envoyer un message complet : envoyer directement toutes les propriétés du message ainsi que son contenu HTML en entrée de la méthode. Votre message sera créé, sauvegardé et réutilisable pour de prochains envois. Pour cela, spécifier un nouveau nom de message en entrée de la méthode et ajouter tous les paramètres nécessaires à l’envoi dans le corps de la requête. A noter, si vous créez un nouveau message e-mail dans le cadre d’un envoi transactionnel horodaté, celui-ci sera expédié et/ou personnalisé avec les informations du contact adressé au moment de l’envoi, et non à la création du message.

Conseils et bonnes pratiques

Pour personnaliser votre message, vous pouvez intégrer dans votre contenu HTML des variables de champs de contacts qui seront automatiquement interprétées et remplacées par le système au moment de l’envoi par les données en base (voir “exemple avec création d’un message” dans la section Request Body ci-dessous). Vous pouvez personnaliser votre message avec les informations contenues dans les champs du contact.

Le lien de désinscription est facultatif dans le cadre d’envois transactionnels. Toutefois, si votre message intègre une notion marketing (recommandations produits, offres promotionnelles, etc.), il est fortement recommandé de conserver ce lien (envoi de type TransactionalMarketing). Cette bonne pratique vous assurera une meilleure délivrabilité et une meilleure expérience utilisateur pour vos contacts qui auront le choix de ne plus recevoir ce type de communication s’ils le désirent.

Pour des raisons de délivrabilité, il est fortement recommandé d’utiliser des noms de domaines distincts pour les envois marketing et pour les envois transactionnels. C’est le choix de l’adresse de l’expéditeur du message qui déterminera le sous-domaine lié à l’envoi. Nous vous conseillons donc de dédier exclusivement un ou plusieurs sous-domaines spécifiques à l’ensemble de vos envois transactionnels.

Tous les nouveaux contacts qui feront l’objet d’un envoi transactionnel de type TransactionalMarketing seront enregistrés dans la base de contacts et seront adressables dans de futurs envois (envoi marketing groupés et/ou transactionnels). En revanche, les nouveaux contacts qui feront l’objet d’un envoi transactionnel de type TransactionalService ne seront pas visibles dans la base de contacts et ne pourront pas être réutilisés depuis la plateforme pour de futurs envois marketing.

Il est recommandé de réutiliser, autant que possible, les mêmes messages afin de pouvoir bénéficier des statistiques agrégées dans vos rapports d’envois transactionnels.

Les consentements importés grâce à cette méthode sont valables uniquement pour les nouveaux contacts de votre base. Vous pourrez exporter, sous forme de fichiers, les preuves de consentement de vos contacts à l’aide du type d’export “Réglementaire / Finalités de traitements”.

En cas de succès, la méthode renverra une chaîne de caractères Result correspondant à l’identifiant unique de l’envoi transactionnel TransactionID (GUID de longueur fixe de 36 caractères avec des tirets) qu’il est fortement recommandé de stocker car nécessaire à la récupération des propriétés de l’envoi transactionnel et de ses statistiques d’envois.

Vous pouvez utiliser la méthode de récupération des statistiques comportementales des contacts agrégées par jour pour un message transactionnel donné.

Dernière mise à jour : Septembre 2020

Authorization

apiKey - X-API-Key

Request Parameters

1 Query Parameter
1 Header

Request Body

4 Examples
Schema
object

Message management

TransactionalSending
object

TransactionalEmailSending

Responses

Transactional sending created.

Schema
object

ResultString

Result
string

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
X-API-Key