Requête unitaire
L’URL pour interroger l’API est :
https://app.cleanmylist.email/_api/request.php?email=[email]&test=[test]&api_key=[api_key]
Un quota d’utilisation est en place, si vous effectuez des requêtes en boucle, appliquez une temporisation de 300ms entre chaque requête.
[api_key] est à remplacer par votre clé API
Elle est disponible dans votre espace membre (Menu déroulant en hait à droite : Gestion du compte > API)
[email] est à remplacer par l’adresse email à tester
[test] = 0 pour ne pas faire de test d’envoi
ou 1 pour faire une simulation d’envoi.
La valeur [test]=1 allonge le temps de réponse.
Le retour est au format JSON en quelques secondes.
Exemple :
{‘quota’:’461774′,’score’:55,’email’:’nadine@sxtxuxoxe.fr’,’valid’:true,’last_delivery’:’2018-11-26 08:10:50′}
Requête multiple
L’URL pour interroger l’API est :
https://app.cleanmylist.email/_api/request_webhook.php
Le retour est envoyé au format JSON plus tard. Les données sont postées sur l’url passée pour votre webhook.
Variables à passer en plus de celles listées précédemment :
[webhook_url] l’url sur laquelle vous souhaitez que l’on poste les résultats
[tab_email] un tableau contenant les emails à tester (jusqu’à 1000). À passer à la place de [email]
[id_callback_webhook] (optionnel) une chaîne de caractères arbitraire qui sera retournée à l’identique dans le webhook. A des fins d’identification des webhooks reçus.
Le quota est retourné lors de l’appel et non dans la réponse renvoyée par un webhook.
Exemple :
{« api_key »: »b5GeG9vT9aW4fO74GP7Ds2XoP9Gs4S2apVGsrX3″, »test »:1, »webhook_url »: »https:\/\/www.example.comm\/_api\/test.php », »tab_email »:[« test@ediware.net », »test1@ediware.net », »test2@ediware.net »]}
Retour :
{« ok »: « 1 », « message »: « X lines imported », « quota » : 3454}
Variables disponibles dans la réponse :
Certaines valeurs ne sont pas toujours présentes. Dans ce cas elles sont indiquées comme « (optionnel) ».
Les dates sont au format SQL : yyyy-MM-DD HH:mm:ss
quota : le crédit restant sur votre compte
Si vous utilisez l’API sur un site, nous vous conseillons de paramétrer une alerte quand le quota devient bas.
email : l’email testé
error (optionnel) : si présent, explique pourquoi l’email ne semble pas valide
Valeurs possibles : NODOMAIN, NOMX, hard_bounce, test_ko (simulation d’envoi échouée), invalid
valid : validité de l’adresse email
Valeurs possibles :
« true » = l’email est à priori viable.
« false » = l’email ne peut pas fonctionner
risk (optionnel) : présent s’il y a un risque quelconque à utiliser cette adresse email
Valeurs possibles :
Il y a différentes valeurs possibles :
« role » , « spam_reporter » (reporte aux organismes antispam), « abuse_reporter » (reporte aux boucles de rétroaction antispam)
abuse (optionnel) : si présent, la valeur est « true » . Cette adresse email a généré plusieurs plaintes aux services abuse
last_activity (optionnel) : date de dernière activité détectée. Si non vide, cela donne la date de dernière activité de l’adresse (ouverture ou clic). C’est avec cette valeur qui permet de qualifier les actifs et segmenter la base : actifs de moins de 6 mois, un an, etc…
last_delivered (optionnel) : date la plus récente à laquelle un email a bien été délivré à cette adresse.
hard_bounce_detected (optionnel) : date de détection NPAI hard. Présent uniquement si « error » vaut « hard_bounce »
spamtrap (optionnel) : si présent, la valeur est « true » , c’est une adresse piège.
spamtrap_detail (optionnel) : si spamtrap est à « true » , cette variable donne le détail
catchall : la valeur est « true » si c’est une adresse catchall. « false sinon, ou si le test n’a pas pu être effectué.
score : un nombre entre 0 et 100
Plus le score est haut, plus l’adresse email est susceptible d’être valide et active. A l’inverse, un score bas indique une adresse erronée, inactive ou problématique.
Pour des opérations de marketing nous vous conseillons d’écarter toutes les adresses ayant un score strictement inférieur à 50.
Pour de la validation d’adresse à la volée, lors d’une inscription sur un site par exemple, nous vous conseillons de régler ce seuil à 30.