Rafale.IO API 10.9 (FR)

INTRODUCTION

Rafale.IO est un système intégré de gestion de mailing lists (campagnes de fidélisation et d’acquisition) et messages transactionnels, appelés « jobs », qui prend en charge l’ensemble des étapes techniques nécessaires à la réalisation d’un envoi de bout en bout : expansion de liste de destinataires, personnalisation des messages, routage avec gestion de la délivrabilité, tracking d’ouvertures et de clics, enregistrement des désabonnements, publication de statistiques temps réel et production de logs et rapports détaillés.


L’interface de programmation de Rafale.IO est disponible en mode asynchrone, par spool de fichiers, et en mode synchrone, via une API RESTful / JSON.


Ces deux APIs accèdent au même espace de travail des comptes utilisateurs : ainsi, un job envoyé par spool de fichiers peut être reprogrammé via l’API REST, et réciproquement, il est possible de demander par spool le rapport d’un job déclenché par l’API REST. 


A chaque utilisateur est alloué un espace de stockage privé, selon l’arborescence suivante :

\REQUEST est le répertoire de dépôt par l’application cliente des commandes au système, telles que : envoi d’un test, d’un emailing, demande de rapports et statistiques. Ce répertoire est spoolé régulièrement par le système pour effectuer le traitement des commandes.


Le répertoire \RESPONSE contient les rapports de traitement des commandes spoolées par le système.


Le répertoire \LOG contient les fichiers de logs quotidiens d’envois, de tracking, de réponses reçues, ainsi que les agrégats horaires.


Le répertoire \REPLY contient les messages de réponse reçus (ex : Challenge-Response, FeedBackLoop, List-Unsubscribe, Out of Office, réponses manuelles…), classés par adresse d’expédition et type.


Enfin, le répertoire \DATA est destiné aux éléments des jobs, tels que les bodys texte, html et AMP, les listes de destinataires et les pièces jointes et images encapsulées, qui doivent y être préalablement uploadés pour pouvoir être exploités par le système.


L’organisation de son arborescence est laissée libre, et peut varier en fonction de la nature des envois, par exemple :


Pour du trafic de fidélisation, avec envoi d’une newsletter à une base d’abonnés, placer la liste des destinataires dans le sous-répertoire \common du répertoire \DATA, et les corps des messages dans un sous-répertoire \DATA\bodys.

Pour du trafic d’acquisition sur fichiers ciblés, créer un sous-répertoire par opération et y copier les éléments du job.


Pour les messages transactionnels simples sans pièces jointes, le contenu des bodys texte/html/amp peut être inclus directement dans l’ordre de routage, et ne nécessite donc pas d’upload préalable.


L’accès à ce répertoire (et les recopies de fichiers) peuvent s’effectuer nativement en partage réseau et en FTP, mais aussi via HTTP, avec des commandes spécifiques d’upload/download de fichiers.

 

Différences mailing lists / messages transactionnels :

 

  1. D’ordinaire, dans les mailing lists, le champ ‘to:’ de chaque email est personnalisé avec l’adresse de son destinataire, et aucun destinataire n’apparaît en ‘cc:’

  2. Tandis que pour les messages transactionnels, chaque destinataire reçoit une copie carbone du même email, avec exactement les mêmes entêtes (‘to:’ ‘cc:’ )

En d’autres termes, et d’un point de vue purement technique :

 

  1. un message transactionnel peut-être assimilé à une mailing list dont les entêtes ‘to:’ et ‘cc:’ sont statiques.

  2. une mailing list peut-être assimilée à un message transactionnel avec champ ‘to:’ personnalisé, et dont l’ensemble des destinataires est donné en ‘bcc:’

 

Pour cette raison, le système fournit une API unique pour les deux types de job, qui permet de traiter de nombreux cas de figure, même spécifiques.


Accessoirement, l’échelle des volumes d’envoi différe sensiblement : de 1 à quelques dizaines de destinataires pour les messages transactionnels, à des mailing list de plusieurs centaines de millers d’adresses, c’est pourquoi, du point de vue du système, un job est qualifié de « mailing list » lorsque qu’un fichier externe de destinataires est spécifié dans l’ordre de routage, tandis qu’un job est qualifié de « message transactionnel » si les destinataires sont uniquement spécifiés dans les champs d’entête ‘to:’, ‘cc:’ et ‘bcc:’ de l’ordre de routage.

1. DONNEES DES JOBS

1.1. Liste de destinataires

Les listes de destinataires utilisées pour les mailing lists doivent être au format .CSV.

 

  • Le nom des champs doit être indiqué sur la première ligne du fichier, avec comme séparateur les caractères spéciaux ’ ;’, ‘,’ ‘<tab>’, ‘|’.

  • Le système détecte automatiquement le séparateur utilisé

  • Les champs et les valeurs peuvent optionnellement être double-quotés

  • Les champs commençants par les lettres ‘RF’ sont interdits car réservés par le système

  • Le champ « EMAIL » doit être défini et contenir l’adresse email du destinataire

  • Le fichier CSV peut contenir au maximum 250 champs

  • La longueur du nom d’un champ est limitée à 24 caractères, dans la plage ‘A’-’Z’, ‘0-9’ et le caractère tiret ‘-‘.

  • La taille des données d’un champ est limitée à 1000 caractères

  • Les noms des champs sont insensibles à la case

  • La longueur totale d’une ligne est limitée à 4000 caractères

  • L’encodage du fichier doit être précisé dans l’ordre de routage (par défaut, "utf-8"", cf "list" : "charset") 

 

Exemple :

 

name;forname;email;company;custid

Smith;John;john.smith@smithcompany.com;thesmithcompany;12345

Andersen;Thomas;t.ansersen@neocompany.com;neocomp;67890

NB : pour les messages transactionnels, le système construit une liste de destinataires à partir des champs ‘to:’ ‘cc: et ‘bcc:’ des entêtes, avec les champs ‘EMAIL’ et ‘NAME’ tels que spécifiés par les membres "addr" et "name".

1.2. Champs de fusion

Les champs d’entêtes des messages (ex : ‘Subject:’), les corps des bodys texte, html ou AMP, peuvent être personnalisés avec n’importe quel champ de la liste des destinataires, à l’aide de la syntaxe suivante : $$[record]nom_du_champ$$.


Le système fournit en outre deux champs de fusion spéciaux :


$$[link]mirror$$ : créé un lien vers une page miroir générée automatiquement par le système à partir du body html, repersonnalisée et avec liens trackés, exactement à l’identique de l’email envoyé


$$[link]unsub$$ : créé un lien vers la page de désinscription indiquée dans la section "tracking", ce qui permet de différencier le click dans les statistiques.


Exemple de header personnalisé :


"header" : {
  "subject" : "$$[record]forname$$, votre offre personnalisée" },…

 

Exemple de body html personnalisé :
 

"htmbody" : {
"path": "Bonjour $$[record]forname$$,
Pour confirmer votre inscription, veuillez <a href="http://mycompany.com/register?id=$$[record]custid$$"> cliquez ici</a>
Pour visualiser ce message dans votre navigateur,
<a href="$$[link]mirror$$">cliquez ici</a>
Pour ne plus recevoir de message de notre part, vous pouvez
<a href="$$[link]unsub$$">vous désinscrire</a>" },…

 

1.3. Champs de date

Les champs de fusions spéciaux permettent la représentation de la date et l’heure de multiples façons, dans plusieurs langues, en fuseau horaire local ou GMT :


$$[XXXdateYYY]FMT,def$$
XXX    ‘gmt’, def=‘local’
YYY    ‘fr’, ‘be’, ‘us’, ‘uk’, ‘esp’, ‘deu’, ‘ita’, def=current country
FMT
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%c Date and time representation appropriate for locale (%m/%/%y %H:%M:%S)
%C Long Date and time representation appropriate for locale
%d Day of month as decimal number (01 – 31)
%H Hour in 24-hour format (00 – 23)
%I Hour in 12-hour format (01 – 12)
%j Day of year as decimal number (001 – 366)
%m Month as decimal number (01 – 12)
%M Minute as decimal number (00 – 59)
%p Current locale's A.M./P.M. indicator for 12-hour clock
%S Second as decimal number (00 – 59)
%w Weekday as decimal number (0 – 6; Sunday is 0)
%x Date representation for current locale
%X Time representation for current locale
%y Year without century, as decimal number (00 – 99)
%Y Year with century, as decimal number
%Z Either the time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown
%e Date and time representation for email header (RFC 822).
%g Local / GMT difference. For example: " +0200"
def    default [section]key

 

Exemples :


$$[date]%e$$          =>    Thu, 20 Jun 2010 14:27:12 +0200
$$[datefr]%c$$        =>    20/06/10 16:27:12
$$[gmtdatefr]%A, %c$$ =>    Dimanche, 20/06/10 16:27:12

1.4. Champs virtuels

Les champs virtuels permettent de créer des valeurs calculées à l’aide d’expressions, constituées d’opérateurs, de fonctions et de tests logiques.


Les expressions sont constituées d’opérandes (constantes et champs de fusion) et d’opérateurs (mathématiques ou fonctions), et sont évaluées en RPN (Reverse Polish Notation).


Les champs virtuels sont définis dans la section [virtual] du fichier de définition du job et sont évalués dans leur ordre de déclaration.


Ce premier exemple personnalise le sujet de l’email si le champ ‘forname’ est renseigné dans la liste CSV, en gérant la majuscule de début de phrase :


"header" : {
  "subject" : "$$[record]greet$$otre offre personnalisée",…
"virtual" : {
  "greet" : "$$[record]forname$$ _len 1 > $$[record]forname$$ _maj \",
             v\" _cat \"V\" ? ",…


L’exemple suivant présente un sujet d’email dont le contenu est préfixé par un message personnalisé selon la date anniversaire du destinataire, tout en gérant la majuscule en début de phrase si le prénom ‘firstname’ n’est pas renseigné :


"header" : {
  "subject" : "$$[record]greet$$otre offre personnalisée”,…
"virtual" : {
  "greet"  : "$$[record]birthdate$$ $$[datefr]%d/%m$$ _beg \"Joyeux
              anniversaire ! \" \"\" ? $$[record]forname$$ _len 1 >
              \"$$[record]forname$$\" _maj \", v\" _cat \"V\" ? _cat",… 


Ci-dessous le details des opérateurs et fonctions disponibles :

1.4.1. Opérateurs

+        addition
-        soustraction
*        multiplication
/        division
%        pourcentage

1.4.2. Test

==        est égal à
!=        est différent de 
>=        supérieur ou égal à
<=        inférieur ou égal à
>>        strictement supérieur à
<<        strictement inférieur à
<>        compris entre deux valeurs
&&        ET logique
||        OU logique
[=        commence par
=]        se termine par
[]        contient
][        ne contient pas
{}        présent dans la liste
}{        absent de la liste

 

1.4.3. Conditions

A B C ?    si A est vrai, alors B sinon C
 

1.4.4. Fonctions

 

_len        longueur de 
_maj        converti les premières lettres des mots en majuscules, le reste
            en minuscules
_upp        converti tout en majuscules
_low        converti tout en minuscules
_cmp        comparaison case insensitive
_str        chaine 1 contient chaine 2
_beg        chaine 1 commence par chaine 2
_end        chaine 1 termine par chaine 2
_usr        extrait le nom d’utilisateur d’une adresse email
_dom        extrait le nom de domaine d’une adresse email
_cat        concatène chaine 1 et chaine 2
_mrg        force l’évaluation des champs de fusion composés

 

1.5. Templates texte / html / AMP

Les contenus des bodys texte, html et AMP peuvent être soit directement encaspulés dans l’ordre de routage sous forme littérale (cf ex ci-dessus), encodés nativement en "utf-8", soit être stockés dans des fichiers externes (en ce cas, penser à spécifier leur encodage dans le champ "charset" dans l’ordre de routage), avec un chemin d’accès précédé du caractère ‘@’ et relatif au répertoire de travail de l’utilisateur. Nb : la description du format AMP est publiée sur https://amp.dev/.


Par exemple :

"htmbody" : {
  "path": "@DATA/news5/news5_body.html”,… }

1.6. Charsets

Les champs "charset" décrivent le jeu de caractère dans lequel sont entrées les valeurs, et sont donc nécessaires pour un encodage correct des messages email, qu’il s’agisse des entêtes ou des templates.


Lorsque le système fusionne les templates avec les champs de la liste de destinataires, il effectue automatiquement la conversion des jeux de caractères entre les données.


Par exemple, si le template est au format UTF-8 et la liste de destinataires en iso-8859, le système convertira les accents des champs de la liste de destinataires en UTF-8 avant de les fusionner avec le body html.

2. API ASYNCHRONE (SPOOL)

Les commandes sont transmises au système par l’intermédiaire de fichiers, déposés dans le répertoire \REQUEST, spoolé par le système.


Leur contenu dépend de la fonction appelée (et peut être vide), et reprend exactelent le flux de donnée de l’API RESTful : la première ligne du fichier contient littéralement la requête HTTP et les paramètres en JSON après la premiere ligne vide (<CR><LF><CR><LF>). Les entêtes HTTP "Authorization:" et "Content-Lenght:" sont facultatives et ignorées par le système, puisque les droits d’accès sont données en amont pour l’accès aux répertoires du comptes utilisateur, et la longueur des données est donnée par le <EOF>.


Pour une bonne prise en compte par le système, ces fichiers doivent respecter une convention de nommage stricte :


A_date=<YYMMDDHHMMSS>_id=<ID>.json

  • <YYMMDDHHMMSS> représente la date souhaitée de prise en compte par le système. Nb : le système ignore le fichier de commande tant que la date n’est pas atteinte.

  • <ID> représente un identifiant unique client obligatoire, chaine de 3 à 30 caractères dans le spectre ‘a’-‘z’ ‘0’-‘9’ et le caractère ‘-‘.

 

Le système utilise ‘ID’ comme nom de fichier pour les données de réponse associées le cas échéant.
 

Si une commande a déjà été transmise avec le même <ID>, le résultat écrase le précédent, attention donc à veiller à l’unicité de l’identifiant pour conserver une trace de tous les traitements du système.
 

Lors de sa prise en compte par le système, le fichier ‘A_date=YYMMDDHHMMSS….json’ est renommé en ‘Y_date=YYMMDDHHMMSS….json’ pendant toute la durée du traitement.

Attention, lors de la création d’un fichier de commande via partage réseau ou FTP, utiliser un nom de fichier temporaire ne commençant pas par ‘A_*’ afin qu’il ne soit pas pris en compte par le système avant que l’intégralité de son contenu ne soit écrit sur disque. Une fois la copie effectuée, renommer le fichier temporaire en ‘A_... ‘. Nb : l’interface HTTP est exempte de ce type de problème.


En cas d’erreur de traitement, le fichier est renommé en ‘X_date=YYMMDDHHMMSS….json’ la clef "stamp" : { "err" :.. , "msg" : …,  } indique la cause de l’erreur.

Si le traitement de la commande s’effectue normalement, le fichier est déplacé dans le répertoire \RESPONSE et renommé en ‘Z_date=YYMMDDHHMMSSjson’, et complèté du code de résultat du traitement dans la clef "stamp" : { "err" :.. , "msg" : …,  }, et les données associées, tel que la demande de journaux, rapports ou statistiques sont disponibles dans le répertoire \RESPONSE\<ID>.<ext>, l’extension dépendant du format de données demandé en sortie, précisé dans les paramètrès de la query ( ?ftm=csv/htm/xml/json)

3. API RESTful / JSON (SYNCHRONE)

L’API RESTful est accessible via l’url :


https//:<server address>/api


L’authentication s’effectue via le header HTTP : 


Authorization : Bearer <apikey> 
 

Le champ <apikey> se configure dans le compte utilisateur déclaré sur le serveur (cf « Rafale.IO – Configuration 10.9 »).
 

Par commodité, il est également possible de transmettre l’ <apikey> dans l’url, sous forme d’un paramètre de la requête :


https//:<server address>/api/<obj>?apikey=<apikey>
 

La plupart des méthodes GET retourne des tableaux d’objets (statistiques, rapports, logs…) dont le format de sortie peut être défini par le paramètre <format> de la requête :
 

https//:<server address>/api/<obj>?format=<csv/htm/xml/json>
 

  • Le format CSV est le plus compact car le nom des champs n’apparait qu’une seule fois en en-tête du tableau.

  • Le format HTM fournit une interface minimaliste pour consulter via un navigateur les principales tables et paramètres du système.

  • Le format XML permet d’importer directement les tables dans les systèmes compatibles nativement avec ce format (ex : « flux de données XML » depuis Excel).

  • Enfin, le format JSON est adapté à la récupération de faibles volumes données structurées.

 

​Les données associées aux méthodes POST et PUT doivent être exclusivement formattées en  JSON.

Exemples d’utilisation avec Curl :
 

curl -X "POST" "https://<server address>/api/jobs" -H "Authorization: Bearer <apikey>" -H "Content-Type: application/json" -d "ordre de routage au format JSON"
 

Le système fournit en réponse un code de statut HTTP et, le cas échéant, des données complèmentaires, formattées en JSON, sous la forme d’un objet "stamp", qui contient à minima un champ de date de traitement de la requête, un code d’erreur numérique et une description du code d’erreur.
 

Transaction type :

<method> api/<objet>?<options> HTTP/1.1
Authorization: Bearer <apikey>
Content-Type: application/json
Content-Lenght: <taille des données JSON ci-dessous>


{
   …
}

-----------------------------------------------------------------------------------------------
HTTP/1.1 <code d’erreur HTTP>
Content-Type: application/json
Content-Lenght: <taille des données JSON ci-dessous>


{
"stamp" :  {
    "date"        : <date de prise en compte YYMMDDhhmmss>,
    "err"         : <code d’erreur, 0=OK>,
    "msg"         : <description du code d’erreur>
    }
}

ou paramètre <code d’erreur HTTP> peut prendre les valeurs suivantes : 

250 OK

Requête traitée avec succès

201 Created

Objet créé avec succès

HTTP Status Code

Description

400 Bad request

Format de la requête invalide

401 Unauthorized

Accès à la ressource non autorisé (droits <apikey>)

403 Forbidden

Accès à l’objet non autorisé (droits <apikey>)

404 Not found

Ressource / objet inexistant

204 No Content

Requête traitée avec succès

Les schémas JSON sont donnés avec des valeurs <description> entre corniers, qui doivent être remplacées par des valeurs réelles conforme à la syntaxe JSON, à savoir les chaines de caractères double quotées (caractère d’échapemment backslash) et encodée en utf-8, les booléens avec les chaines non quotées true et false, et les nombres sans quote.

4. FICHIERS

En premier lieu, même si ce n’est pas strictement nécessaire pour les messages transactionnels sans pièces jointes ni images encapsulées, comme indiqué précédement, il est nécessaire d’uploader dans l’espace de stockage du compte utilisateur les éléments qui seront référencés dans les ordres de routage :

POST api/files/<path>

upload un fichier dans le répertoire utilisateur. Si <path> contient des répertoires, ils seront automatiquement créés. 3 niveaux de sous-répertoires autorisés. L’opération échoue si le fichier existe déjà.

PUT api/files/<path>

idem POST, à la difference que le fichier uploadé écrase toute version précédente.

GET api/files/

retourne la liste des fichiers du répertoire racine du compte utilisateur

GET api/files/<path>

si path est un répertoire, retourne la liste des fichiers du répertoire, sinon, le fichier complet.

DEL api/files/<path>

supprime le fichier <path>.

Method

Description

NB : cet objet n’a de sens que dans le cadre de l’API RESTful, puisqu’en asynchrone, l’accès aux fichiers du compte client s’effectue en partage réseau ou FTP.
 

Ces méthodes permettent donc l’upload de listes de diffusion, bodys, pièces jointes et images au format natif, sans conversion Base64 et encaspulation dans un objet JSON.
 

Exemple d’upload du fichier news5_body.htm dans le sous-répertoire \DATA\NEWS5 du compte utilisateur :

 

POST api/files/DATA/NEWS5/news5_body.htm HTTP/1.1
Authorization: Bearer <apikey>
Content-Type: text/html
Content-Lenght: <taille du fichier htm>

 

<html>This is the html body…     </html>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>


{
"stamp" :  {
    "date"        : <date de prise en compte YYMMDDhhmmss>,
    "mailno"      : <reference système sous laquelle est enrgistrée le job>,
    "err"         : <code d’erreur, 0=OK>,
    "msg"         : <description du code d’erreur>
    }
}

Exemple de download de fichier de réponse à une requête de demande de statistiques d’un job  :

GET api/files/RESPONSE/<ID requete>.csv HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/csv
Content-Lenght: <taille du fichier csv en octets>


"rfdate";"rfipno";"rfipstr";"rfsdno";"rfsdstr";"rfdmno";"rfdmstr";"rfmxno";…


<EOF>

5. JOBS

POST api/jobs

Créé un nouveau job et lance les envois

PUT api/jobs/<rfmailno>

Modifie les propriétés du job <rfmailno> (date de début/fin, nombre d’essais…)

GET api/jobs

Liste l’ensemble des jobs du compte utilisateur et leurs principaux indicateurs de statut et statistiques

GET api/jobs/<rfmailno>/stats

Retourne les statistiques détaillées d’envoi et de tracking du job <rfmailno>, ventilées par [IP,sd,dm,mx]

GET api/jobs/<rfmailno>/report

Retourne le rapport d’envoi du job <rfmailno>

GET api/jobs/<rfmailno>/clicks

Retourne les statistiques des clics ventilés du job <rfmailno>

GET api/jobs/<rfmailno>/<data>

Retourne le contenu des éléments natifs du job (txtbody/htmbody/ampbody/list)

Method

Description

5.1. Envoyer un job

Cette méthode crée un nouveau job (message transactionnel ou mailing list) et lance les envois, et retourne le résultat de l’opération dans la section "stamp" de la réponse.

POST api/jobs HTTP/1.1
Authorization: Bearer <apikey>
Content-Type: application/json
Content-Lenght: <taille en octet des données JSON ci-dessous>

 

{
 "job" : {
    "ref"         :  <reference du job (3-30 chars ‘a’-‘z’ ‘0’-‘9’ ‘-‘>,
    "title"       :  <intitule du job>,
    "tags"        :  [ <liste de mots clefs de recherches>,… ],
    "datestart"   :  <date de début des envois, au format YYMMDDhhmmss>,
    "datestop"    :  <date de fin des envois, au format YYMMDDhhmmss>
    "retrynb"     :  <nombre de ré-essais>
    "retrydelay"  :  <délai entre les ré-essais>
    }, 

 

 "header" : { 
    "subject"     :  <subject de l’email>,
    "from"        :  { "addr": <email de l’expéditeur> , "name": <nom de
                       l’expéditeur > },
    "sender"      :  { "addr": <email du sender > , "name": <nom du sender> },
    "reply-to"    :  { "addr": <email de réponse> , "name": <nom de réponse> },
    "to"          :  [ { "addr" : <email du destinataire>, "name" : <nom du
                       destinataire> },… ],
    "cc"          :  [ { "addr" : <email du destinataire>, "name" : <nom du
                       destinataire> },… ],
    "bcc"         :  [ { "addr" : <email du destinataire>, "name" : <nom du
                       destinataire> },… ],
    "feedback-id" :  <champ feedback-id (Google) au format_a:b:c:d>,
    "precedence"  :  <champ precedence (Google) true/false>,
    "unlst"       :  <champ List-Unsubscribe : liens http/smtp/both>,
    "charset"     :  <charset d’encodage du header des emails, def utf-8>
    },

 

  "list" : {
    "path"        : <@path de la liste des destinataires au format csv>,
    "charset"     : <charset d’encodage de la liste>,
    "testaddr"    : [<liste d’emails de test >,… ],
    "checkaddr"   : [<liste d’emails pour envoi depuis chaque IP >,… ],
    "filter"      : [<liste de blacklistes utilisées pour le filtrage>,… ]
    },

 

  "virtuals" : { { <nom du champ virtuel> : <expression>,… },
    },

 

  "txtbody" : {
    "path"        : <contenu littéral ou @path du fichier body txt>,
    "encoding"    : <format d’encodage du body, def Quote-Printable>,
    "charset"     : <charset du fichier body txt>
    },

 

  "htmbody" : {
    "path"        : <contenu littéral ou @path du fichier body htm>,
    "encoding"    : <format d’encodage du body, def Quote-Printable>,
    "charset"     : <charset du fichier body htm>
    },

 

  "ampbody" : {
    "path"        : <contenu littéral ou @path du fichier body amp>,
    "encoding"    : <format d’encodage du body, def Quote-Printable>,
    "charset"     : <charset du fichier body amp>
    },

 

  "attachments" : [ {
    "path"        : <@path du fichier de la pièce jointe>,
    "encoding"    : <format d’encodage de la pièce jointe, def Base64>,
    },… ],

 

  "images" :  [ {
    "path"        : <@path du fichier de l’image encapsulée>,
    "encoding"    : <format d’encodage de l’image, def Base64>,
    },… ],


  "routing" : {
    "ip"          : <liste d’adresses IP d’émission>,
    "sender"      : <nom de domaine utilisé dans les emails d’expédition>,
    "envelopefrom": <adresse utilisée dans l’email de MAILFROM : verp/from/sender>,
    "sign"        : <flag de signature DKIM : true/false>,
    "ssl"         : <flag d’utilisation de STARTTLS : true/false>,
    "route"       : <passerelle de routage, def remise directe MX>
    },

 

  "tracking" : {
    "host"        : <nom de domaine utilisé pour les URL trackées>,
    "open"        : <option de tracking d’ouverture : disable/image/pixel>,
    "click"       : <option de tracking de clics : disable/short/embedded>,
    "image"       : <option de tracking d’images : disable/short/embedded>,
    "bot"         : <option d’insertion de lien masqué : true/false>,
    "unsub"       : <lien vers la page de désabonnement>,
    "uncfm"       : <lien vers la page de confirmation de désabonnement>,
    "mirror"      : <lien vers la page mirroir>
    }
}

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille en octet des données JSON ci-dessous>


{
  "rfstamp" :  {
    "rfdate"        : <date de prise en compte YYMMDDhhmmss>,
    "rfmailno"      : <reference système sous laquelle est enrgistrée le job>,
    "rferr"         : <code d’erreur, 0=OK>,
    "rfmsg"         : <description du code d’erreur>
    }
}

Objet "Job" :


Si "datestart" est non précisée, départ immédiat.
Si "datestop" est non précisée, arrêt du job automatique après le dernier cycle de réessais.
 

Objet "Header" :


Selon la configuration du compte utilisateur et des paramètres de routage définis dans "routing", le domaine indiqué dans l’adresse email dans la clef "addr" de "from" est susceptible d’être remplacé par un autre domaine, tel que le ReverseDNS de l’IP d’émission par exemple. Pour cette raison, il est valide de définir une adresse "addr" de "from" avec uniquement la partie <user> de l’adresse email complète <user@domain>. Par exemple :


"header"  : {  "from" : { "addr" : "info",… },…
"routing" : {  "domain" : "mysender.com",… },…

 

     =>  From: <info@mysender.com>
 

Le champ "unlst" génère un header ‘List-Unsubsribe :’ dans les entêtes des emails envoyés, qui peut contenir deux types de liens : un mailto smtp pour des désabonnents asynchrones (valeur "smtp"), ou http pour un désabonnement synchrone (valeur "http"), ou les deux, à la discrétion du système de réception (valeur "both").


Le jeu de caractère indiqué dans "charset" précise l’encodage de destination des messages (def : "utf-8"). Rappel : les chaines de caractères dans un fichier JSON doivent être au format natif utf-8.
 

Objet "XXXbody" :


Il est nécessaire d’avoir au moins un des trois bodys valides, txt, htm ou amp.


Les bodyparts des sections non déclarées ne sont pas insérées, et n’importe quelle combinaison est autorisée : txt brut seul, htm seul, amp seul, txt/htm, txt/amp, htm/amp, txt/htm/amp.
 

Objet "List" :
 

Si "list" : "path" n’est pas précisé, le système constitue la liste des destinataires d’après les champs "to", "bb" et "bcc" définis dans "header", avec deux colonnes :email et name.
Dans le contexte d’une mailing list, "list" : "path" doit contenir le chemin d’accès d’une liste de destinataires. Le système ignore les "addr" indiquées dans "header" pour l’expédition, puisqu’il s’agit de champs statiques. Pour personnaliser le champ "to" pour chaque destinataire, indiquer une seule entrée dans le "header" :


"to" : [ { "addr" : "$$[record]email$$", "name" : "$$[record]name$$" } ]
 

Si "testaddr" indique au moins une adresse email valide, le système considère que c’est un envoi de test, pour validation sur des emails internes avant envoi aux véritables destinataires finaux.


Afin de s’assurer d’un parfait rendu des personnalisations, le système fusionne les emails avec les données originales de la liste des destinataires (en particulier les champs custom), mais effectue leur remise uniquement sur les adresses email de test. Dans cette configuration, le sujet de l’email est préfixé de "[TEST] ", et les toutes fonctions de désabonnements sont désactivées.


Si "checkaddr" indique au moins une adresse email valide, le système considère que c’est un envoi de vérification du statut des IPs. Son fonctionnement est identique aux emails de test, à la différence près que système effectue l’envoi du message sur chaque destinaire depuis chaque IP spécifié dans "routing" : "ip".


Dans la liste des jobs, le champ "type" indique le type du job, avec les valeurs :

  • ‘L‘ : List (mailing List)

  • 'M’ : Message (transactionnal Message)

  • ‘T’ : Test

  • ‘C’ : Check

 

Objet "Routing" :
 

Les paramètres de cet objet sont susceptibles d’être fixés au niveau de la configuration du compte utilisateur, et donc non modifiables au niveau de l’ordre de routage.


Si "ip" n’est pas précisé, le système utilise toutes les IPs déclarées comme autorisées dans le compte utilisateur.


Si "domain" n’est pas précisé, le système utilise celui par défaut configuré dans le compte utilisateur (si ce dernier n’est pas précisé, le système utilise le ReverseDNS de l’IP d’émission, cf « Rafale.IO – Configuration 10.9 »).


Le champ "envelopefrom" peut contenir trois valeurs :

  • "verp" (Variable Envelope Return Path), qui génère une adresse email de bounce unique pour chaque destinataire avec comme domaine le RDNS de l’IP d’émission, utilisée en ‘MAILFROM :’ de la session SMTP

  • "from", c’est-à-dire la valeur indiquée dans "header" : { "from" : "addr" }.

  • "sender", c’est-à-dire la valeur indiquée dans "header" : { "sender" : "addr" }.

 

Le champ "route" permet d’indiquer une passerelle de remise plutôt qu’un envoi direct du message au MX de destination. Cela peut-être un relai SMTP tiers, mais également un compte Cloud (Azure ou EC2, voir « Rafale.IO – Cloud API 1.0 »). Le relai SMTP tiers doit être déclaré sur le système dans \DOMAINS, au même titre que les autres groupes de destination (ex : @myisprelay) et configuré avec les paramètres techniques du relai (IP/login/passw).


Objet "Tracking" :


Les paramètres de cet objet sont susceptibles d’être fixés au niveau de la configuration du compte utilisateur, et donc non modifiables au niveau de l’ordre de routage.


Si "domain" n’est pas précisé, le système utilise celui par défaut configuré dans le compte utilisateur (si ce dernier n’est pas précisé, le système utilise le ReverseDNS de l’IP d’émission, cf « Rafale.IO – Configuration 10.9 »). Si un domaine est indiqué, un enregistrement de type ‘A’ de sa zone DNS doit pointer vers une des adresses IP en écoute sur le port 80 du serveur.
 

Le champ "open", pour les options de tracking d’ouverture, peut avoir trois valeurs : ‘disable’ : aucun tracking n’est effectué ; ‘pixel’ : le lien vers une image d’1x1 blanche est insérée dans le code body html; ‘image’ : le système effectue une redirection d’URL sur le premier tag <img…> trouvé dans le code du body html.
 

Le champ "mirror" est facultatif, il peut préciser une URL externe pour la page mirroir de l’email envoyé, le système générant nativement des pages mirroirs personnalisées et trackées à la volée à partir du body html.
 

Les champs "unsub" et "uncfm" peuvent préciser des URLs externes pour les pages de désabonnement de de confirmation de désabonnement, mais sont en général fixées dans la configuration du compte utilisateur. Les URLs peuvent également être locale, avec un chemin d’accès relatif au répertoire \wwws de l’application.
 

Objet "Stamp" :
 

Le système retourne le résultat du traitement de la requête d’envoi de job dans la section "stamp". Le champ "rfmailno" représente le numéro de référence interne du jobpar lequel peuvent être effectuées toutes les opérations ultérieures : demande de rapport, de statistiques, reprogrammation, suspension et redémarrage, etc.
 

5.2. Modifer un job
 

PUT api/jobs/<rfmailno> HTTP/1.1
Authorization: Bearer <apikey>
Content-Type: application/json
Content-Lenght: <taille en octet des données JSON ci-dessous>

 

{
"status" :  {
    "hold"         : <true/false>,
    },
"job" : {
    "datestart"   :  <date de début des envois, au format YYMMDDhhmmss>,
    "datestop"    :  <date de fin des envois, au format YYMMDDhhmmss>
    "retrynb"     :  <nombre de réessais>
    }, 
 "header" : { 
    "subject"     :  <subject de l’email>,
    } 
}

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>


{
"stamp" :  {
    "date"        : <date de prise en compte YYMMDDhhmmss>,
    "err"         : <code d’erreur, 0=OK>,
    "msg"         : <description du code d’erreur>
    }
}

La clef "status" permet de suspendre la diffusion du job avec effet immédiat. Le job reste en état suspendu tant qu’il n’a pas été relancé via une requête fixant la valeur de "hold" à false.


La clef "job" permet de reprogrammer dates de début et de fin des envois du job, ainsi que le nombre de d’essais d’envois.


Enfin "header" permet la modification du sujet des emails en cours de diffusion.

5.3. Liste des jobs

GET api/jobs/<rfmailno>?from=<index_from>&to=<index_to>
     &fmt=<csv/htm/xml/json_output_file_format>    HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>

 

{
  "jobs" : [ {
    "ref"         : <référence du job>,
    "type"        : <‘L’ pour une mailing List, ‘M’ pour un Message
                      transactionnel, ‘T’ pour un Test et ‘C’ pour Check>,
    "rfmailno"    : <référence système du job>,
    "rfstart"     : <date de début d’envoi YYMMDDHHMMSS>,
    "rfstop"      : <date de fin d’envoi YYMMDDHHMMSS>,
    "rfsts"       : <statut du job (voir tableau ci-dessous)>,
    "rfstr"       : <intitulé du statut>,
    "rfrsn"       : <cause du statut>,
    "rfrecfirst"  : <compteur interne>,
    "rfrecidx"    : <compteur interne>,
    "rfrecbusy"   : <nombre de jobs total en file d’attente>,
    "rfrecfeed"   : <dernier nombre de jobs injectés dans la file d’attente>,
    "rflistsize"  : <nombre total de destinataires de la liste>,
    "rffiltered"  : <nombre de destinataires filtrés à l’injection>,
    "rfdiscarded" : <nombre de destinataires filtrés au routage>,
    "rfsyserr"    : <nombre de jobs en erreur système>,
    "rfdelivered" : <nombre d’emails délivrés>,
    "rfsoft"      : <nombre de destinataires en erreur temporaire>,
    "rfhard"      : <nombre de NPAI>,
    "rfflow"      : <nombre total de changement de flow au cours du routage>,
    "rfptrn"      : <nombre total de patterns SMTP NON reconnus>,
    "rfopen"      : <nombre total d’ouvertures>,
    "rfopener"    : <nombre total d’ouvreurs>,
    "rfclick"     : <nombre total de clics>,
    "rfclicker"   : <nombre total de cliqueurs>,
    "rfmirror"    : <nombre de destinataires ayant lu le mail en ligne (page miroir)>,
    "rfunsub"     : <nombre de destinataires ayant cliqué sur le lien de désabonnement>,
    "rfuncfm"     : <nombre de destinataires ayant cliqué sur le lien de confirmation>
,
    "rfunlst"     : <nombre de destinataires désabonnés à l’aide du TAG List-Unsubscribe>,
    "rfbot"       : <nombre de destinataires ayant cliqué sur le lien invisible>,
    "rffbl"       : <nombre de FeedBackLoop reçues>,
    "rfreply"     : <nombre de réponses par email reçues>,
    "datestart"   : <date de début d’envoi programmée>,
    "datestop"    : <date de fin d’envoi programmée>,
    "retrynb"     : <nombre de repasses programmées>,
    "retrydelay"  : <délai en heures entre les repasses>,
    "title"       : <titre du job>,
    "tags"        : <mots clef du job>,
    "subject"     : <sujet de l’email>,
    "fromaddr"    : <adresse email de l’expéditeur (sans le domaine)>,
    "fromname"    : <nom de l’expéditeur>,
    "toaddr"      : <adresse email du premier destinataire>,
    "toname"      : <nom du premier destinataire>,
    "ccaddr"      : <adresse email du premier destinataire en copie>,
    "ccname"      : <nom du premier destinataire en copie>,
    "bccaddr"     : <adresse email du premier destinataire en copie cachée>,
    "bccname"     : <nom du premier destinataire en copie cachée>,
    "rftextsz"    : <taille du body text (en octets)>,
    "txtbody"     : <lien vers le body txt>,
    "rfhtmsz"     : <taille du body htm (en octets)>,
    "htmbody"     : <lien vers le body html>,
    "rfampsz"     : <taille du body AMP (en octets)>,
    "ampbody"     : <lien vers le body AMP>,
    "list"        : <lien vers la liste originale des destinataires>,
    "rflinknb"    : <nombre total de liens trackés>,
    "rfattchsz"   : <taille totale des pièces jointes>,
    "rfattchnb"   : <nombre de pièces jointes>,
    "rfimagenb"   : <nombre d’images encapsulées>,
    "rfimagesz"   : <taille totale des images encapsulées>
    },… ]
}

 

rfsts

Description

Intitulé

1

Job soumis au système

Submitted

2

Job en cours d’exécution

Running

3

Job terminé

Completed

4

Job en attente de datestart

Waiting

5

Job suspendu manuellement

Suspended

6

Job en erreur

Error

Query :

 

Le paramètre "rfmailno" est facultatif. Si non précisé, le système retourne par défaut les 100 derniers jobs injectés dans le système par l’utilisateur. Il est possible de modifier cette étendue à l’aide des paramètres "from" et "to", avec un intervalle de 1000 résultats à la fois maximum. Si  le paramètre "rfmailno" est précisé, le système retourne uniquement l’entrée du tableau correspondant à la référence du job et ignore les autres paramètres de la requête.


5.4. Statistiques détaillées des jobs

GET api/jobs/<rfmailno>/stats?groupby=<flag de regroupement>
     &fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>

 

{
  "stats" : [ {
    "rfdate"      : <toujours à 0)>,
    "rfipno"      : <numéro interne de l’IP d’émission>,
    "rfipstr"     : <adresse IP d’émission>,
    "rfsdno"      : <numéro interne du sender>,
    "rfsdstr"     : <domaine de sender>,
    "rfdmno"      : <numéro interne du groupe de domaines>,
    "rfdmstr"     : <nom du groupe de domaines>,
    "rfmxno"      : <numéro interne du MX>,
    "rfmxstr"     : <adresse IP du MX>,
    "rfmxdm"      : <numéro interne du groupe de domaines rattaché au MX>,
    "rfmxds"      : <nom du groupe de domaines rattaché au MX>,
    "rflistsize"  : <nombre de destinataires par groupe de domaines
                     (pré calculé à l’injection selon les alias connus)>,
    "rfdelivered" : <nombre d’emails délivrés>,
    "rfsoft"      : <nombre de destinataires en erreur temporaire>,
    "rfhard"      : <nombre de NPAI>,
    "rfflow"      : <nombre total de changement de flow au cours du routage>,
    "rffallback"  : <nombre total de transmission sur MX secondaire>,
    "rfopen"      : <nombre total d’ouvertures>,
    "rfopener"    : <nombre total d’ouvreurs>,
    "rfclick"     : <nombre total de clics>,
    "rfclicker"   : <nombre total de cliqueurs>,
    "rfmirror"    : <nombre total de clics sur page mirroir>,
    "rfunsub"     : <nombre total de clics sur lien de désabonnement>,
    "rfuncfm"     : <nombre total de clics sur le lien de confirmation>,
    "rfunlst"     : <nombre désabonnements à l’aide du TAG List-Unsubscribe>,
    "rfbot"       : <nombre total de clics sur lien invisible>,
    "rffbl"       : <nombre de FeedBackLoop reçues>,
    "rfreply"     : <nombre de réponse par email reçues>
    },… ]
}

 

Query :

 

Cette commande génère des statistiques de delivery et tracking de la campagne référencée par la variable ‘mailno’, issue du journal des campagnes.


Les principaux indicateurs (emails délivrés, hardbounces, ouvertures, clics, …) sont ventilés par quadruplets uniques { ip ; sd ; dm ; mx }, où ‘ip’ représente d’IP d’émission, ‘sd’ le domaine de sender, ‘dm’ le groupe de domaines de destination, et ‘mx’ l’IP du serveur SMTP distant.


"listsize" représente le nombre de destinataires par groupe de domaine, tel que précalculé selon les alias connus à l’injection du job dans le système.


Le paramètre GROUPBY représente la valeur décimale du Ou Logique (OR) des flags suivants :

  • STAT_FLAG_IP 0x08

  • STAT_FLAG_SD 0x04

  • STAT_FLAG_DM 0x02

  • STAT_FLAG_MX 0x01

5.5. Rapports d'envoi de job

GET api/jobs/<rfmailno>/report?&fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>

 

{
  "report" : [ {
    "rfevt"       : <code de statut (voir ci-dessous)>,
    "rfstr"       : <intitulé du statut>,
    "rfpatten"    : <nom du pattern détecté>,
    "rfpoolno"    : <poolno spécifique>,
    "rfcancelnb"  : <nombre d’expirations en file d’attente>,
    "rfsenddate"  : <date de l’envoi {YYMMDDHHMMSS}>,
    "rfduration"  : <durée totale de traitement du job (ms)>,
    "rfipno"      : <numéro de l’IP d’émission>,
    "rfipstr"     : <adresse IP d’émission>,
    "rfsdno"      : <numéro du sender>,
    "rfsdstr"     : <domaine de sender>,
    "rfdmno"      : <numéro du groupe de domaines>,
    "rfdmstr"     : <nom du groupe de domaines>,
    "rfmxno"      : <numéro du MX>,
    "rfmxstr"     : <adresse IP du MX>,
    "rfmxname"    : <nom d’hôte du MX>,
    "rfmxdm"      : <numéro du groupe de domaines rattaché au MX>,
    "rfmxds"      : <nom du groupe de domaines rattaché au MX>,
    "rfmxdx"      : <numéro du MX dans la liste>,
    "rfmxnb"      : <nombre de MX>,
    "rfipflow"    : <numéro du profil de contrôle de flux IP lors de l’envoi>,
    "rfsdflow"    : <numéro du profil de contrôle de flux SENDER>,
    "rftryno"     : <numéro de l’essai>,
    "rfssno"      : <numéro du message dans la session SMTP>,
    "rfdforge"    : <surée de fusion/personnalisation du message (ms)>,
    "rfdsign"     : <surée de signature DKIM (ms)>,
    "rfsize"      : <taille en octet du message>,
    "rfssl"       : <version du protocole SSL/TLS négocié dans la session>,
    "rferr"       : <numéro de la dernière erreur enregistrée>,
    "rfapp"       : <dernier code d’erreur applicatif>,
    "rfdwe"       : <numéro de la dernière erreur système enregistrée>,
    "rfval"       : <dernier code XXX reçu>,
    "rfstp"       : <dernière étape du protocole effectuée>,
    "rfclientip"  : <adresse IP du client http>,
    "rflasthit"   : <dernier évènement de tracking>,
    "rflastclick" : <dernier clic reçu>,
    "rfopennb"    : <nombre total d’ouverture>,
    "rfopen"      : <date de dernière ouverture>,
    "rfclicknb"   : <nombre total de clics>,
    "rfclick"     : <date du dernier clic>,
    "rfmirror"    : <date de première consultation de la page miroir>,
    "rfunsub"     : <date de premier clic sur lien de désinscription>,
    "rfuncfm"     : <date de premier clic sur lien de confirmation de
                     désinscription>,
    "rfunlst"     : <date de premier hit sur lien List-Unsubscribe>,
    "rfbot"       : <date de premier hit sur lien invisible>,
    "rffbl"       : <date de réception du message de FeedBackLoop>,
    "rfreply"     : <date de réception du message de réponse>,
    "rfreplytype" : <type de réponse reçue>,
    "rfdevice"    : <terminal de consultation du client>,
    "rfbrowser"   : <navigateur web du client>,
    "email"       : <adresse email du destinaire>,
    <champ custom>: <valeur du champ custom>,
    <champ custom>: <valeur du champ custom>,
    <champ custom>: <valeur du champ custom>,
    …
    <champ custom>: <valeur du champ custom>
    },… ]
}

 

rfevt

Description

Intitulé

1

Adresse email vide

Empty

2

Format de l’adresse email invalide

Invalid

3

Adresse présente dans la blackliste xxx

BL xxx

4

Adresse email en doublon dans la liste

Duplicate

21

Email remis avec succès

Delivered

23

Hard Bounce – voir rfstr pour le détail

Hard

26

Erreur système

System

25

IP/MX/banner filtré

Discarded

24

Changement de sets de paramètres suite à match pattern SMTP

Flow

22

Soft Bounce – voir rfstr pour le détail

Soft

5.6. Ventilation des clics d'un job

GET api/jobs/<rfmailno>/clicks?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille du fichier json en octets>

{
  "clicks" : [ {
    "no"          : <numéro du lien dans le body>,
    "nb"          : <nombre total de clicks sur le lien dans le job>,
    "url"         : <url de redirection>
    },… ]
}

 

5.7. Téléchargement des éléments

GET api/jobs/<rfmailno>/<txtbody/htmbody/ampbody/list> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/<content type>
Content-Lenght: <taille en octet des données ci-dessous>

 

<requested data>

6. LOGS

6.1. Logs de routage (MTA)

GET api/logs/<YYMMDD>/rfmta?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/json
Content-Lenght: <taille en octet des données JSON ci-dessous>

 

{
  "rfmta" : [ {
    "rfsenddate"     : <date de l’envoi {YYMMDDHHMMSS}>,
    "ref"            : <référence l’opération>,
    "email"          : <adresse email du destinataire>,
    "rfevt"          : <code de statut (voir ci-dessous)>,
    "rfstr"          : <détail du code de statut>,
    "rfpattern"      : <nom du pattern détecté>,
    "rfmailno"       : <référence système du job>,
    "rfrecno"        : <numéro du destinataire dans la liste>,
    "rfpoolno"       : <numéro du pool d’IP d’émission>,
    "rfipno"         : <numéro de l’IP d’émission>,
    "rfipstr"        : <adresse IP d’émission>,
    "rfsdno"         : <numéro du sender>,
    "rfsdstr"        : <domaine de sender>,
    "rfdmno"         : <numéro du groupe de domaines>,
    "rfdmstr"        : <nom du groupe de domaines>,
    "rfmxno"         : <numéro du MX>,
    "rfmxstr"        : <adresse IP du MX>,
    "rfmxname"       : <nom d’hôte du MX>,
    "rfmxdx"         : <numéro du MX dans la liste>,
    "rfmxnb"         : <nombre de MX>,
    "rfmxdm"         : <numéro du groupe de domaines rattaché au MX>,
    "rfmxds"         : <nom du groupe de domaines rattaché au MX>,
    "rfipflowno"     : <numéro du profil de contrôle de flux IP lors de l’envoi>,
    "rfipflowstr"    : <nom du profil de contrôle de flux IP lors de l’envoi>,
    "rfsdflowno"     : <numéro du profil de contrôle de flux SENDER>,
    "rfsdflowstr"    : <nom du profil de contrôle de flux SENDER>,
    "rfdnssrv"       : <adresse IP du serveur DNS utilisé pour la résolution MX>,
    "rfipport"       : <port IP de connexion SMTP>,
    "rfssno"         : <numéro du message dans la session SMTP>,
    "rftryno"        : <numéro de l’essai>,
    "rfenvelopefrom" : <type d’adresse de sender utilisé>,
    "rfssl"          : <version du protocole SSL/TLS négocié dans la session>,
    "rfsslc"         : <SSL/TLS Cipher>,
    "rfsslh"         : <SSL/TLS Hash>,
    "rfssle"         : <SSL/TLS Exch>,
    "rfsize"         : <taille en octet du message>,
    "rfval"          : <dernier code XXX reçu>,
    "rfapp"          : <dernier code d’erreur applicatif>,
    "rferr"          : <numéro de la dernière erreur enregistrée>,
    "rfdwe"          : <numéro de la dernière erreur système enregistrée>,
    "rfstp"          : <dernière étape du protocole effectuée>,
    "rfduration"     : <durée totale de la session (ms)>,
    "rfdjob"         : <durée totale de traitement du job (ms)>,
    "rfdlookup"      : <durée de résolution DNS du domaine de destination (ms)>,
    "rfdcnt"         : <durée d’établissement de la connexion (ms)>,
    "rfdforge"       : <durée de fusion/personnalisation du message (ms)>,
    "rfdsign"        : <durée de signature DKIM (ms)>,
    "rfbanner"       : <message d’accueil du serveur de destination>,
    "rfqueued"       : <message de confirmation de réception de l’email>,
    "rfsnt"          : <dernière commande SMTP envoyée>,
    "rfrcv"          : <dernière réponse SMTP reçue>,
    "rfpath"         : <chemin d’accès au message original>,
    "rftrcref"       : <référence de la trace>,
    "rftrcoff"       : <offset de la trace>,
    "rftrclen"       : <taille de la trace>
    },… ]
}

rfevt

Description

Intitulé

21

Email remis avec succès

Delivered

23

Hard Bounce – voir rfstr pour le détail

Hard

26

Erreur système

System

25

IP/MX/banner filtré

Discarded

24

Changement de sets de paramètres suite à match pattern SMTP

Flow

22

Soft Bounce – voir rfstr pour le détail

Soft

6.2. Logs de tracking

GET api/logs/<YYMMDD>/rftrack?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/<content type>
Content-Lenght: <taille en octet des données ci-dessous>

 

{
  "rftrack" : [ {
    "rfhitdate"   : <date du hit HTTP {YYMMDDHHMMSS}>,
    "ref"         : <référence l’opération>,
    "email"       : <adresse email du destinataire>,
    "rfevt"       : <code de l’évènement (voir ci-dessous)>,
    "rfstr"       : <intitulé de l’évènement>,
    "rfprm"       : <paramètres complémentaire de l’évènement>,
    "rfsrc"       : <source de l’évènement (0=body txt,1=htm,2=amp,3=miroir)>,
    "rfmailno"    : <référence système du job>,
    "rfrecno"     : <numéro du destinataire dans la liste>,
    "rfipno"      : <numéro de l’IP d’émission>,
    "rfipstr"     : <adresse IP d’émission>,
    "rfsdno"      : <numéro du sender>,
    "rfsdstr"     : <domaine de sender>,
    "rfdmno"      : <numéro du groupe de domaines>,
    "rfdmstr"     : <nom du groupe de domaines>,
    "rfmxno"      : <numéro du MX>,
    "rfmxstr"     : <adresse IP du MX>,
    "rfserverip"  : <adresse IP de réception du hit http (ou https)>,
    "rfipport"    : <port IP de réception du hit http (ou https)>,
    "rfclientip"  : <adresse IP du client http>,
    "rfhttphost"  : <entête HTTP ‘Host:’>,
    "rfssno"      : <numéro de la transaction dans la session http>,
    "rfduration"  : <durée de la communication (ms)>,
    "rfdevice"    : <terminal de consultation du client>,
    "rfbrowser"   : <navigateur web du client>,
    "rfurl"       : <URL originale de la requête http>,
    "rfreferer"   : <entête HTTP ‘Referer:’>,
    "rfuseragent" : <entête HTTP ‘User-Agent:’>,
    "rftrcref"    : <référence de la trace>,
    "rftrcoff"    : <offset de la trace>,
    "rftrclen"    : <taille de la trace>
    },… ]
}

rfevt

Description

Intitulé

61

Ouverture du message

Open

62

Consultation page miroir

Mirror

63

Hit URL List-Unsuscribe

Unlst

64

Hit lien de désinscription

Unsub

65

Hit lien de confirmation de désinscription

Uncfm

66

Hit lien invisible

Bot

101-399

Hit lien de tracking

Clic

6.3. Logs de messages reçus

GET api/logs<YYMMDD>/rfrelay?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/<content type>
Content-Lenght: <taille en octet des données ci-dessous>

 

{
  "rfrelay" : [ {
    "rfrelaydate" : <date de la réception du message {YYMMDDHHMMSS}>,
    "ref"         : <référence l’opération>,
    "email"       : <adresse email du destinataire>,
    "rfevt"       : <code de l’évènement (voir ci-dessous)>,
    "rfstr"       : <intitulé de l’évènement>,
    "rfprm"       : <paramètres complémentaire de l’évènement>,
    "rfmailno"    : <référence système du job>,
    "rfrecno"     : <numéro du destinataire dans la liste>,
    "rfipno"      : <numéro de l’IP d’émission>,
    "rfipstr"     : <adresse IP d’émission>,
    "rfsdno"      : <numéro du sender>,
    "rfsdstr"     : <domaine de sender>,
    "rfdmno"      : <numéro du groupe de domaines>,
    "rfdmstr"     : <nom du groupe de domaines>,
    "rfmxno"      : <numéro du MX>,
    "rfmxstr"     : <adresse IP du MX>,
    "rfserverip"  : <adresse IP de réception du message SMTP>,
    "rfportip"    : <port IP de réception de la sessions SMTP (ou STMPS)>,
    "rfclientip"  : <adresse IP du client SMTP>,
    "rfssno"      : <numéro de la transaction dans la session SMTP>,
    "rfssl"       : <version de SSL/TLS négociée dans la session>,
    "rfduration"  : <durée de la communication (ms)>,
    "rfsize"      : <taille de l’email reçu, en octets>,
    "rfehlo"      : <message de présentation du client SMTP>,
    "rfmailfrom"  : <adresse de sender de la session SMTP>,
    "rfrcptto"    : <adresse de destinataire de la session SMTP>,
    "rfrcptno"    : <numéro du destinataire>,
    "rfrcptnb"    : <nombre de destinataires>,
    "rfpath"      : <chemin d’accès au fichier email reçu (relatif à \REPLY)>,
    "rftrcref"    : <référence de la trace>,
    "rftrcoff"    : <offset de la trace>,
    "rftrclen"    : <taille de la trace>
    },… ]
}

rfevt

Description

Intitulé

41

Message de retour sur adresse List-Unsubscribe

Unlst

42

Message de retour de FeedBackLoop

FBL

43

Message de « challenge response »

Challenge

44

Message de retour de hard bounce

Hard

45

Message de retour de soft bounce

Soft

46

Message de retour de plainte

Complain

47

Message de retour sur mailfrom verp

Verp

48

Message de réponse au fromaddr

Reply

49

Message de retour sur l’adresse dmarc@sender

DMARC

6.4. Agrégats horaires

GET api/logs/<YYMMDD>/rfagg?fmt=<csv/htm/xml/json_output_file_format> HTTP/1.1
Authorization: Bearer <apikey>

-----------------------------------------------------------------------------------------------HTTP/1.1 200 OK
Content-Type: application/<content type>
Content-Lenght: <taille en octet des données ci-dessous>

 

{
  "rfagg" : [ {
    "rfdate"      : <tranche horaire (0 = 0h00-0h59)>,
    "rfipno"      : <numéro interne de l’IP d’émission>,
    "rfipstr"     : <adresse IP d’émission>,
    "rfsdno"      : <numéro interne du sender>,
    "rfsdstr"     : <domaine de sender>,
    "rfdmno"      : <numéro interne du groupe de domaines>,
    "rfdmstr"     : <nom du groupe de domaines>,
    "rfmxno"      : <numéro interne du MX>,
    "rfmxstr"     : <adresse IP du MX>,
    "rfmxdm"      : <numéro interne du groupe de domaines rattaché au MX>,
    "rfmxds"      : <nom du groupe de domaines rattaché au MX>,
    "rflistsize"  : <nombre de destinataires par groupe de domaines
                     (pré calculé à l’injection selon les alias connus)>,
    "rfdelivered" : <nombre d’emails délivrés>,
    "rfsoft"      : <nombre de destinataires en erreur temporaire>,
    "rfhard"      : <nombre de NPAI>,
    "rfflow"      : <nombre total de changement de flow au cours du routage>,
    "rffallback"  : <nombre total de transmission sur MX secondaire>,
    "rfopen"      : <nombre total d’ouvertures>,
    "rfopener"    : <nombre total d’ouvreurs>,
    "rfclick"     : <nombre total de clics>,
    "rfclicker"   : <nombre total de cliqueurs>,
    "rfmirror"    : <nombre total de clics sur page mirroir>,
    "rfunsub"     : <nombre total de clics sur lien de désabonnement>,
    "rfuncfm"     : <nombre total de clics sur le lien de confirmation>,
    "rfunlst"     : <nombre désabonnements à l’aide du TAG List-Unsubscribe>,
    "rfbot"       : <nombre total de clics sur lien invisible>,
    "rffbl"       : <nombre de FeedBackLoop reçues>,
    "rfreply"     : <nombre de réponse par email reçues>
    },… ]
}

7. MESSAGES DE RETOUR

 

Rafale gère les messages de retour reçus suite aux envois, qui peuvent être de plusieurs natures : FeedBackLoop, List-Unsubscribe par email, rapports DMARC, Hard et Soft Bounces, Challenge-Response, et réponses - automatiques ou non.


Pour chaque sender utilisé, qu’il s’agisse des ReverseDNS des IP, ou de noms de domaines spécifiés dans les paramètres de job (ex :  [smtp]domain), le système créé un sous-répertoire du sender dans \REPLY\, ainsi qu’une sous-arborescence de tri, dans laquelle sont stockés les messages reçus en fonction de leur type, sous forme de fichiers horodatés :

 

  • @CHALLENGE contient les messages identifiés comme Challenge-Response par détection de pattern

  • @DMARC contient les messages reçus sur l’adresse email de l’enregistrement DMARC

  • @FBL contient les messages de FeedBackLoop reçus sur une l’adresse email de notification déclarée lors de l’inscription

  • @HARD contient les messages identifiés comme Hard Bounce par détection de pattern

  • @SOFT contient les messages identifiés comme Soft Bounce par détection de pattern

  • @UNLST contient les messages de désinscription automatique par email (Tag List-Unsubscribe)

  • @VERP contient les messages reçus sur l’adresse de session SMTP (MAIL FROM) lorsque l’option [smtp]envelopefrom est fixée à ‘verp’ (cf 2.2.1), et dont le contenu n’a pu être qualifié

  • 'abuse' et 'postmaster' sont des adresses statiques associées au sender (abuse@sender et postmaster@sender), créés automatiquement par le système car souvent nécessaires à l’inscription aux programmes de FeedBackLoop.

 

Lors de l’injection d’un job, le système créé automatiquement un répertoire d’adresse statique correspondant à l’adresse de sender définie dans [header]fromaddr (cf 2.6).
 

Il est possible de créer manuellement un répertoire @CATCHALL qui acceptera tous les messages du domaine de sender sur des adresses inexistantes (il s’agira probablement de spam).
 

Le contenu des fichiers est le flux brut de données tel que reçu pendant la session phase DATA de la session SMTP (message RFC822).