L’API Sendkit permet d’envoyer des emails en utilisant un template Sendkit et de personnaliser leur contenu pour chaque destinataire.
Pour utiliser un template et transmettre des données de personnalisation, les deux headers suivants sont nécessaires :
X-SKT-TEMPLATE : permet de sélectionner le template Sendkit à utiliser.
X-SKT-SUB : permet de transmettre les données de personnalisation pour chaque destinataire.
Il est nécessaire que le template utilisé soit créé dans Sendkit puis “Mes campagnes”. En effet, il n’est pas possible d’appeler directement un modèle Studio via l’API. En revanche, vous pouvez créer un template Sendkit en utilisant un modèle Studio comme base.
Dans l’exemple suivant :
le template utilisé s’appelle name1 ;
les champs de personnalisation sont FirstName et LastName.
curl --request POST \
--url https://api.sarbacane.com/sendkit/email/send \
--header 'content-type: application/json' \
--header 'x-apikey: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' \
--data '{
"to": [
{
"address": "[email protected]"
}
],
"msg": {
"from": {
"address": "[email protected]",
"personalName": "Frank Sender"
},
"replyTo": {
"personalName": "Frank Sender",
"address": "[email protected]"
},
"subject": ".",
"html": "."
},
"headers": {
"X-SKT-TEMPLATE": "name1",
"X-SKT-SUB": [
{
"email": "[email protected]",
"values": {
"FirstName": "John",
"LastName": "Doe"
},
"meta": {
"orderId": 1234567890,
"shipmentId": 123456789
}
}
],
"X-SKT-TEXTVERSION": 1,
"X-SKT-TAGS": [
"Test",
"Sendkit",
"Shipping",
"Hello"
]
}
}'
Important : le champ html est obligatoire
Dans l’exemple ci-dessus, le contenu est simplement ".", car il sera automatiquement remplacé par le contenu du template indiqué dans X-SKT-TEMPLATE.
Le header X-SKT-SUB permet de transmettre des données spécifiques à chaque destinataire.
Il peut notamment être utilisé pour :
remplacer des variables dynamiques ;
personnaliser le contenu de l’email par destinataire ;
ajouter des données métier ;
personnaliser le sujet ;
gérer du contenu conditionnel ;
transmettre des données qui ne sont pas affichées dans l’email.
Les possibilités sont nombreuses. Par exemple, vous pouvez utiliser les données de votre système d’information pour :
afficher des produits complémentaires ;
modifier certains éléments du contenu ou du CSS ;
générer un sujet différent pour chaque destinataire ;
afficher des informations liées à une commande ou une livraison.
Vous pouvez ajouter des variables dans le contenu de votre template.
Par exemple :
Bonjour {{FirstName}} {{LastName}},
Puis transmettez les valeurs correspondantes dans X-SKT-SUB :
"values": {
"FirstName": "John",
"LastName": "Doe"
}
Le header X-SKT-META vous permet d'ajouter des éléments personnalisés sous forme de clé-valeur. Les éléments contenus dans le header meta ne sont pas présents dans l'email de destination. Seuls les webhooks vous permettent de récupérer ces informations et de les traiter dans votre système.
Il peut par exemple contenir :
un identifiant utilisateur ;
un numéro de commande ;
un identifiant de livraison ;
toute autre donnée permettant de faire le lien avec votre système d’information.
Exemple :
"meta": {
"unique_id": "987654321",
"order_id": "132456798",
"shipment_id": "1237498798"
}
Attention si une clé existe à la fois dans X-SKT-META et X-SKT-SUB, la valeur du SUB est prioritaire.
Le header X-SKT-TEXTVERSION permet de générer automatiquement une version texte à partir du contenu HTML de l’email.
Exemple :
"X-SKT-TEXTVERSION": 1
Le header X-SKT-TAGS permet d'associer des tags à l’email afin de filtrer et analyser les statistiques dans Sendkit. Vous pouvez ainsi différencier les emails de type "renouvellement de mot de passe" ou de "bienvenue" ou encore selon leurs provenances. Les tags ne sont évidemment pas visibles par vos destinataires.
5 tags maximum par email ;
seuls les 5 premiers tags sont conservés ;
50 caractères alphanumériques maximum par tag ;
les caractères spéciaux ne sont pas autorisés (@, -, ,, etc.).
Exemple :
"X-SKT-TAGS": [
"Test",
"Sendkit",
"Shipping",
"Hello"
]
Par défaut, le domaine d’envoi est déduit de l’adresse de l’expéditeur.
Le header X-SKT-DOMAIN permet de forcer le domaine utilisé pour l’envoi.
Exemple :
"X-SKT-DOMAIN": "sendkit.example.com"
Important : si le domaine indiqué n’est pas totalement configuré et validé dans Sendkit, un domaine mutualisé pourra être utilisé pour l’envoi.
Le header X-SKT-TRACKING permet d’activer ou de désactiver le suivi des interactions avec l’email.
Il permet notamment de gérer :
le tracking des ouvertures ;
le tracking des clics.
Exemple :
"X-SKT-TRACKING": {
"html": {
"open": 1,
"click": 1
},
"text": {
"click": 1
}
}
Le header X-SKT-GOOGLEANALYTICS permet d’activer et de personnaliser le suivi Google Analytics sur les liens contenus dans l’email.
Exemple :
"X-SKT-GOOGLEANALYTICS": {
"enable": "1",
"utm_source": "Sendkit_Support",
"utm_medium": "email",
"utm_content": "Test_Sending",
"utm_campaign": "Have_a_look"
}
Les paramètres UTM permettent d’identifier la provenance et le contexte des clics dans vos outils d’analyse.
Header | Utilisation |
X-SKT-TEMPLATE | Sélectionner le template Sendkit à utiliser |
X-SKT-SUB | Personnaliser l’email pour chaque destinataire |
X-SKT-META | Ajouter des données globales accessibles via les webhooks |
X-SKT-TEXTVERSION | Générer une version texte à partir du HTML |
X-SKT-TAGS | Ajouter des tags pour filtrer et analyser les statistiques |
X-SKT-DOMAIN | Forcer le domaine d’envoi |
X-SKT-TRACKING | Configurer le tracking des ouvertures et des clics |
X-SKT-GOOGLEANALYTICS | Configurer le suivi Google Analytics |
Avec X-SKT-TEMPLATE et X-SKT-SUB, vous pouvez ainsi utiliser un template Sendkit tout en personnalisant dynamiquement son contenu pour chaque destinataire.
