Mettre en place une campagne e-mail

La première étape de la conception de votre campagne consistera à la créer en définissant ses paramètres généraux.

Pour cela, il convient d'utiliser l'opération POST/entity/{e}/mail

Vous devrez tout d'abord renseigner l'entité sur laquelle cette campagne sera créée.

Ensuite, le corps de la requête devra contenir les paramètres généraux de votre campagne sous forme de code JSON :

• "contentType" : l'unique valeur par défaut est HTML. En effet, la création d'une campagne e-mail par API implique obligatoirement l'import d'un fichier HTML pour en établir le contenu.

• "encoding" : la manière dont l'e-mail est encodé. Par exemple, UTF-8 ou ISO-8859-15.

• "entityOfTarget" : l'entité de la table de profils visée par votre campagne.

• "from" : l'expéditeur de l'e-mail, qui apparaîtra dans l'entête de l'e-mail.

• "goalTracking" : si vous avez mis en place des goals, indiquer ce paramètre optionnel comme "true" vous permettra d'effectuer le suivi des goals déclenchés par cette campagne. Il faut alors préciser l'identifiant du goal dans le paramètre "id".

• "name" : le nom de la campagne. Il s'agit du nom qui apparaîtra dans l'interface ACTITO. Il pourra également être utilisé comme nom technique pour identifier la campagne lors du paramétrage des futurs appels.

• "replyTo" : lors de l'envoi d'une campagne e-mail, il est possible d'indiquer une adresse de réponse à laquelle les réponses des destinataires seront transmises. Si ce paramètre optionnel n'est pas rempli, l'adresse par défaut de votre licence sera utilisée.

• "sendingGroups" : ce paramètre optionnel reprend la liste des groupes d'envois auquel cet e-mail appartient. Par défaut, un e-mail est toujours assigné à un groupe d'envoi regroupant tous les e-mails visant la même entité et la même base de profils.

• "supportedLanguages" : les langues dans lesquelles vous voulez envoyer votre campagne. A ce stade, il n'est possible d'envoyer une campagne que dans une seule langue à la fois.

• "targetTable" : le nom de la table de profils visée par votre campagne.

Exemple de requête incluant du code JSON et de réponse : (Téléchargez cet exemple)

La réponse à la requête sera l'identifiant technique auto-généré de la campagne, qui pourra être utilisé pour identifier la campagne lors du paramétrage des futurs appels.

Définir le sujet d'un e-mail

Après avoir créé la base de votre compagne, vous devez en définir le sujet, tel qu'il apparaîtra dans l'entête de votre e-mail.

Pour cela, vous pouvez utiliser l'opération PUT/entity/{e}/mail{m}/content/subject

Les paramètres à renseigner pour cette opération sont :

• l'entité sur laquelle est stockée la campagne

• l'identifiant de la campagne e-mail : il peut s'agir de son id auto-généré ou de son nom technique tel que vous l'avez défini à l'étape précédente.

• le sujet à mettre en place dans votre e-mail : veuillez noter qu'il n'est pas possible de mettre en place des personnalisations de sujet

Exemple de requête et de réponse : (Téléchargez cet exemple)

La réponse à la requête sera l'identifiant technique auto-généré de la campagne.

Définir le ciblage d'un e-mail

Il n'est pas possible de directement faire appel au module de ciblage via les webservices. En revanche, il est possible d'établir des filtres en référence avec les abonnements et les langues, ainsi que de faire appel à un ciblage sauvegardé.

Vous avez également la possibilité de définir le ciblage via l'import d'une liste de profils identifiés sur base d'un attribut unique dans votre base de données.

Comme toute campagne créée par API est directement disponible dans l'interface ACTITO, vous gardez à tout moment la possibilité de cibler vos profils via le module de ciblage de l'interface.

Définir le contenu de votre e-mail

Le contenu de votre e-mail pourra être défini directement par les webservices. Pour cela, il devra obligatoirement être mis en place sous forme de contenu HTML.

Pour définir le contenu de votre e-mail, il convient d'utiliser l'opération : POST/entity/{e}/mail{m}/content/body

Les paramètres à définir sont :

• l'entité sur laquelle est stockée la campagne

• l'identifiant de la campagne e-mail (id ou nom technique)

• "charset" : il s'agit du format du fichier importé (par exemple, UTF-8)

• "inputFile" : il s'agit du fichier zippé contenant le HTML qui définira votre contenu

Deux formats sont possibles pour le fichier de contenu que vous allez importer :

• un seul fichier HTML contenant les images en absolu (les images sont alors hébergées sur un autre serveur)

• un fichier ZIP, contenant un ou plusieurs fichiers HTML en fonction du nombre de langues de votre campagne e-mail. Dans le cas d'une campagne multilingue, il faut ajouter le symbole '_' suivi du code à deux lettres du langage (par exemple : '_FR') comme suffixe du nom de fichier. Les fichiers HTML doivent figurer dans le dossier racine du ZIP.

Mettre en place un fichier de personnalisations

Seules les personnalisations basées sur des attributs pourront bénéficier de la correspondance automatique lors de leur mise en place. Pour les variables externes, il sera nécessaire d'importer un fichier de personnalisation externe.

Ce fichier sera lui aussi basé sur les attributs de profil, mais il va permettre d'y associer des données externes. Pour chaque valeur spécifique d'un attribut, vous allez pouvoir associer une valeur de personnalisation. Il s'agit d'une personnalisation individuelle, car le fichier doit se baser sur un attribut clé. Cela vous permettra d'associer une valeur unique pour chaque profil (par exemple, un code de réduction unique pour chaque attribut "customerId").

Les paramètres à définir sont :

• l'entité sur laquelle est stockée la campagne

• l'identifiant de la campagne e-mail (id ou nom technique)

• "key" : renseignez le nom technique de l'attribut unique qui va servir de clé pour associer chaque profil à votre personnalisation

• le format du fichier de personnalisations : il peut s'agit d'un fichier CSV (il faut alors préciser le séparateur) ou d'un fichier Excel (.xls ou .xlsx)

• "charset" : il s'agit du format du fichier importé (par exemple, UTF-8)

• "inputFile" : il s'agit du fichier zippé contenant votre fichier de personnalisations

Votre fichier doit respecter certaines contraintes au niveau de son format :

• Il doit contenir au moins deux colonnes, mais peut en contenir plus si plusieurs variables se basent sur le même attribut clé.

• La première colonne doit contenir les valeurs pour l'attribut clé, qui permettront de relier les personnalisations à chaque profil. Les colonnes suivantes doivent contenir les valeurs pour ces personnalisations.

• L'entête des colonnes doit correspondre exactement au nom technique de l'attribut clé et du nom des variables des personnalisations. Par exemple, si vous avez sélectionné l'attribut "customerId" comme clé et inclus deux personnalisations dans votre HTML ($code et $variable), les entêtes de vos colonnes devront être : "customerId;code;variable".

La réponse à la requête sera l'identifiant technique auto-généré de la campagne.

Envoyer des e-mails tests

Les APIs d'ACTITO peuvent servir à envoyer des e-mails tests, afin de vous permettre de vérifier la paramétrisation et le contenu de votre campagne.

Vous aurez la possibilité de choisir une série de profils pour tester l'e-mail avec les personnalisations propres à chacun d'eux. Vous pourrez cependant choisir de ne pas réellement envoyer d'e-mail à ces profils, mais de choisir une ou plusieurs adresses e-mails internes sur lesquelles le test doit arriver. Cette option est vivement conseillée.

Pour cela, vous pouvez utiliser l'opération POST/entity/{e}/mail{m}/test

Vous devrez renseigner l'entité sur laquelle est stockée la campagne, l'identifiant de la campagne, puis les données du test sous forme de code JSON dans le paramètre "testInformation" :

• "key" : il s'agit de l'attribut de profil unique utilisé comme clé pour identifier les profils sur lesquels les e-mails de test sont basés.

• "values" : vous pourrez indiquer les valeurs propres à chaque profil test pour l'attribut clé sélectionné.

• "recipients" : ceci vous permet de spécifier une liste d'adresses e-mail qui recevront les tests. Ces adresses ne doivent pas nécessairement figurer dans la base de données. Si aucune adresse n'est mentionnée dans ce paramètre, les profils de test recevront réellement les e-mails.

Exemple d'appel pour l'envoi de tests envoyés à une adresse interne et basés sur 4 profils identifiés par un numéro de client : (Téléchargez cet exemple)

La réponse à la requête sera l'identifiant technique auto-généré de la campagne.

Envoyer la campagne e-mail

Une fois que votre e-mail est prêt, c'est à dire que vous avez défini ses paramètres, choisi les profils ciblés, conçu le message, mis en place les personnalisations, et que vous êtes satisfaits des tests, vous pouvez procéder à l'envoi de votre campagne.

Ceci est possible via l'opération PUT/entity{e}/mail{m}/send

Il suffit pour cela de renseigner l'entité à laquelle appartient la campagne ainsi que l'identifiant de la campagne (id auto-généré ou nom technique). L'envoi des e-mails sera alors immédiat.

Deux paramètres optionnels de requête vous permettent de modifier le comportement d'envoi :

• "sendingMoment" : ceci vous permet de planifier votre envoi à une date ultérieure de votre choix. Par exemple, il faut utiliser le format suivant : 22/05/2019 15:00:00

• "onlyOneEmail" : si l'adresse e-mail n'est pas défini comme un attribut unique dans votre base de données, il se peut qu'elle contienne plusieurs profils avec la même adresse e-mail. En définissant ce paramètre comme "true", vous vous assurez qu'un seul e-mail soit envoyé par adresse e-mail.

Exemple de requête et de réponse pour un envoi planifié : (Téléchargez cet exemple)

La réponse à la requête sera l'identifiant technique auto-généré de la campagne.

Activer une campagne continue

L'envoi continu devra préalablement être préparé, comme détaillé dans les opérations précédentes. Il devra ensuite être activé.

Cela se fait via l'opération PUT/entity/{e}/mail/{m}/activate

Les paramètres à renseigner sont l'entité sur laquelle est enregistrée la campagne et l'identifiant de la campagne.

Vous obtiendrez l'identifiant technique de l'envoi en réponse et la campagne sera dès lors activée.

Contacter un profil avec un envoi continu

Lorsqu'un profil remplit les conditions liées à l'objet de votre envoi continu, le déclenchement de celui-ci est possible via l'opération POST/entity/{e}/mail/{p}/profile{p}

Les paramètres à renseigner pour cet appel sont :

• l'entité sur laquelle la campagne est enregistrée

• l'identifiant de la campagne (id auto-généré ou nom technique)

• l'identifiant du profil visé (profileId ou couple "attributClé=valeur")

• des variables :

Obtenir les informations générales d'une campagne

Vous pouvez obtenir les informations d'une campagne en particulier via l'opération GET/entity/{e}/mail{m}

En spécifiant l'entité et l'identifiant de la campagne visée, vous obtiendrez les paramètres généraux de la campagne visée (tels que la table de profils ciblée, son entité, la langue de la campagne, ...)

Exemple de requête et sa réponse : (Téléchargez cet exemple)

Obtenir les informations générales de campagnes sur base de critères

Vous pouvez obtenir les informations d'une ou plusieurs campagnes sur base de critères via l'opération GET/entity{e}/mail

En plus de l'entité, vous pouvez utiliser les paramètres suivants en tant que filtre :

• "name" : vous pouvez faire une recherche sur le nom des campagnes. En insérant un astérisque au début ou à la fin du terme de recherche, vous pouvez rechercher toutes les campagnes sont le nom débute ou finit par ce terme.

• "type" : vous pouvez choisir de ne cibler que les envois de masse (MASS_SENDING) ou les envois continus (CONTINUOUS).

• "dateFilter" : il s'agit d'un filtre sur la date basé soit sur le moment de création ou de mise à jour, avec un opérateur logique et la date cible de votre choix.

La réponse obtenue sera similaire à la méthode précédente, mis à part que vous pourrez obtenir plusieurs campagnes, selon vos critères.

Récupérer le sujet d'une campagne

Vous pouvez obtenir le sujet d'une campagne via l'opération GET/entity{e}/mail{m}/content/subject en utilisant l'entité et l'identifiant de l'e-mail comme paramètres.

La réponse obtenue sera le sujet de l'e-mail visé sous forme de chaîne de caractères.

Récupérer le contenu d'une campagne

Si vous désirez vous baser sur le contenu d'un e-mail passé pour votre prochaine campagne, vous pouvez en récupérer le contenu HTML, qu'il ait été défini dans l'interface ou via API.

Pour cela, vous pouvez utiliser la méthode GET/entity/{e}/mail{m}/content/body en utilisant l'entité et l'identifiant de l'e-mail comme paramètres.

Vous obtiendrez ainsi le contenu HTML directement dans le corps de la réponse.

Récupérer le fichier de personnalisation d'une campagne

Vous pouvez récupérer le fichier de personnalisation d'une campagne via l'opération GET/entity/{e}/mail{m}/personalization en utilisant l'entité et l'identifiant de l'e-mail comme paramètres.

Le fichier sera accessible via l'URL ainsi obtenue.

Cette opération est possible à la fois pour les campagnes e-mails crées par API et via l'interface ACTITO, mais uniquement pour les personnalisations mises en place via un fichier de personnalisations externes.