Envoyer des emails transactionnels
Pourquoi les utiliser?
Les emails transactionnels peuvent prendre plusieurs aspects:
- Email de confirmation en double optin
- Email de bienvenue
- Confirmation de paiement
- Relance de panier
- Envoi de facture...
Mais ils ont plusieurs points communs :
- Il faut les envoyer rapidement. Tout de suite après une action de l'internaute.
- Leur contenu est personnalisé pour chaque individu
L'api Oneshot répond à ce cas d'usage et vous permet d'utiliser vos ips d'envois Mindbaz pour vos emails transactionnels.
Un envoi oneshot doit être associé à un id de campagne. Cette campagne servira à consulter vos statistiques (ouvertures, npai...). Le oneshot utilisera également les paramètres de cette campagne comme valeur par défaut pour son envoi. Par ex, concernant le code HTML de votre message transactionnel, vous avez 2 possibilités :
- Utiliser le code HTML défini dans la campagne Mindbaz
- Le passer en paramètre des méthodes oneshot
Modes de fonctionnement
Vous fournissez le contenu html et texte
Vous générez vous même le contenu de vos messages et le passez directement en paramètre de chaque appel du oneshot.
Pour cela, faire un POST sur /api/{idsite}/OneShot avec en entrée par exemple:
{
"campaignId": 9543,
"subscriberId": 34,
"messageHTML": "<html><body>ma campagne ici</body></html>"
}
Limitations :
- Le contenu des messages pouvant être différent à chaque appel, nous ne stockons par l'historique des messages et ne pouvons pas afficher la page miroir.
- Si vous utilisez des tags de personnalisation ([[FIELD.XX]]) dans votre message HTML/TXT ou objet, vous devez spécifier les ids des champs utilisés dans le paramètre idFields. Si non spécifiés, les ids 0,1,7,8,13,14,15 sont utilisés par défaut.
- Le tracking mindbaz ne fonctionnera que pour les ouvertures. Les liens ne seront pas trackés car les urls pouvant changer entre plusieurs oneshots, les liens trackés ne sont plus identifiables. Il existe cependant une solution en rendant dynamiques les urls des liens trackés. A l’aide de tags de perso, l’url trackée restera la même et sera identifiable. (Cf "Rendre dynamique le contenu d’un Oneshot" pour plus d'info)
Le contenu html et texte provient de la campagne mindbaz
Le code html est identique pour chaque appel. Vous pouvez donc gérer directement le code html de vos emails transactionnels dans votre campagne mindbaz. Le tracking des liens et des ouvertures fonctionneront.
Pour cela, faire un POST sur /api/{idsite}/OneShot avec en entrée:
{
"campaignId": 9543,
"subscriberId": 34
}
Les codes de retour
Un code de retour est envoyé dans le paramètre data de la réponse :
| Code | description |
|---|---|
| OK | le oneshot est envoyé |
| KO(CAMP_DELETED) | si la campagne campaignId est supprimée. |
| KO(EMAIL_NOTFOUND) | si l’email en entrée n’existe pas. |
| KO(EMAIL_UNSUB) | si l’email est désabonné ou assaini. Vous pouvez autoriser l’envoi de votre oneshot sur un statut désabonné si votre campagne est de type Transactionnel (Type=" Transac"). |
| KO(SMTP_ERROR)[...] | une erreur smtp est survenue sur les ips. La cause peut être trop de plaintes spam sur l’ip ou une vitesse d’envoi trop rapide. Un retry est nécessaire (de préférence après plusieurs heures). |
Rendre dynamique le contenu d’un Oneshot
Rendre dynamique le contenu du message permet de transformer son message en “template”. Le code HTML de votre campagne sera identique pour tous les appels de oneshot d’une campagne mais son contenu changera en fonction de l’abonné. Cela facilite la maintenance du code, les appels sont plus rapides et le tracking des liens devient possible.
La méthode la plus simple est d’utiliser les tags de personnalisation. Par ex, [[FIELD.0]] affiche l’id de l’abonné, [[FIELD.1]] sont email, [[FIELD.14]] son nom, etc. C’est très pratique si vous devez afficher une information se trouvant déjà dans la table d’abonné.
Par contre, si cette information n’est pas à disposition dans cette table, il existe une autre solution. Ce cas de figure se présente souvent lorsque la donnée à afficher est fraîche ou si son import dans la base de données mindbaz est trop coûteux. Cela peut être le contenu d’un panier abandonné par ex.
Ces données peuvent être envoyées sous la forme d’un json en même temps que l’appel du oneshot dans le paramètre emailData. Voici un ex avec 2 champs de perso:
"emailData" = "{
name : 'greg',
product_name : 'iphone 13'
}"
Pour utiliser ces 2 valeurs dans mon code HTML, il faut utiliser le tag [[json.parameter]]. Dans notre exemple, [[json.name]] afficher “greg” et [[json.product_name]] affichera “iphone 13”.
Voici un ex complet en php :
<?php
session_start();
include 'mbzApi.php';
$access_token = GetAccessToken('user_*****','***********' );
$service_url = 'https://api.mindbaz.com';
$dbId = '1234';
//send oneshot to subscriber id 667175 with campaign id 11991
$fields = array("campaignId" => 11991,
"subject" => "test oneshot",
"messageHTML"=> "bonjour [[json.name]], <br>produit acheté : [[json.product_name]]",
"emailData"=>"{ name : 'greg', product_name : 'iphone 13' }",
"subscriberId" => 667175
);
$result = api_call($service_url . '/api/'.$dbId.'/OneShot',$access_token,HttpMethod::POST, $fields );
?>
Envoyer un oneshot avec pièce jointe
Vous pouvez passer des pièces jointes dans vos appels de oneshot (ceci n’est pas possible avec les envois de campagnes classiques).
Pour fournir les pièces jointes, vous devez renseigner le paramètre “attachments”, sous forme d’un tableau d'éléments {“fileContent”,”fileName”}
- fileContent: contenu du fichier encodé en base64
- fileName: nom du fichier en pièce jointe.
- Seuls les fichiers pdf sont acceptés!
- Le nombre maximum de pièces jointes autorisées est de 3
- Le poids total des fichiers ne doit pas dépasser 2 Mo.
Voici un ex en php qui ajoute une pièce jointe card.pdf:
<?php
session_start();
include 'mbzApi.php';
$access_token = GetAccessToken('user_********','********' );
$service_url = 'https://api.mindbaz.com';
$dbId = '1234';
$fileName = "card.pdf";
$fileContent = file_get_contents("C:\\filepath\\".$fileName);
$fileContent = base64_encode($fileContent);
//send oneshot to subscriber id 667175 with campaign id 11991
$fields = array("campaignId" => 11991,
"subject" => "test oneshot avec piece jointe",
"attachments" => array(
array("fileContent"=>$fileContent,"fileName"=>$fileName)
),
"subscriberId" => 667175);
$result = api_call($service_url . '/api/'.$dbId.'/OneShot',$access_token,HttpMethod::POST, $fields );
?>
Statistiques
Vous pouvez retrouver les statistiques de vos envois oneshot directement dans l'interface de l'application ou avec l’api Statistics/campaigns. Si le même id de campagne est utilisé par des envois oneshot sur plusieurs journées, un id d'envoi est créé automatiquement chaque jour. De cette manière, vous pouvez accéder aux statistiques de votre campagne jour par jour.
Rate limiting
Afin d'empêcher l'utilisation abusive du webservice pour envoyer des emails en masse, nous limitons le nombre d'appels par ip à 4000 appels par minute. Tant que le volume d’appel dépassera ce seuil, une erreur http 429 sera retournée.