Cette page documente l'utilisation des fonctions de l'API REST.

Seules les fonctionnalités principales sont disponibles. Certaines fonctions ne sont disponibles que dans l'API SOAP.
Les données doivent être soumises en UTF-8 si elle comportent des caractères spéciaux ou des accents.

Paramétrage du compte

Récupérer la clé API REST

Dans votre compte, rendez-vous sur la page Gestion du compte > API / Zapier > Clé pour l'API REST et Zapier
et demandez une clé API si la fonction n'est pas encore activée.

Déclarer vos IP

Déclarez les IP de vos applications qui vont accéder à l'API REST, séparées par des virgules.

L'authentification à l'API REST s'effectue à la fois à l'aide de l'IP de la machine interrogeant l'API et de la clé API.

Hormis pour les fonctions dont le point d'accès est en https://www.mdworks.fr/api_http_open/...
Ces fonctions d'affichage ou de statistiques sont ouvertes depuis n'importe quelles IP.

Gestion des erreurs

En cas d'erreur, l'API retourne une chaine au format JSON avec le détail de l'erreur :

{

"error": "1",

"message": "Error api_key invalid"

}

Exemple de code en PHP

$url = 'https://www.mdworks.fr/api_http/unsub_global_add';
$data = array('api_key' => 'BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3', 'domain' => 'test_api2@gmail.com');
$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => json_encode($data)
    )
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);

Gestion des utilisateurs

Liste des sous-comptes

Cette fonction permet de récupérer la liste des sous-comptes existant sous votre compte principal.

URL à utiliser : https://www.mdworks.fr/api_http/user_list

Données à poster :

  • api_key : votre clé API

Exemple de données postées :

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"
}
Cette fonction retourne une chaine JSON contenant un tableau d'objets ayant cette structure :
  • id : ID unique du sous-compte
  • log : login unique du sous-compte
  • pass : mot de passe du sous-compte
  • nom : nom du sous-compte (facultatif, utilisé pour l'affichage)
  • email : email du contact technique du sous-compte (utilisé pour envoyer les rapports de plaintes et les rapports de délisting)
  • quota : quota d'envoi attribué au sous-compte
  • classe_domaines : id du pool d'IP attribué au sous-compte (cf. liste des pools d'IP disponibles)
[

{

"id": "2123",

"log": "user1",

"nom": "Nom 1",

"email": "tes@test.com",

"quota": "250000",

"classe_domaines": "7"

},

{

"id": "2124",

"log": "user2",

"pass": "password",

"nom": "Nom 2",

"email": "tes@test.com",

"quota": "12354",

"classe_domaines": "8"

},

{

"id": "2125",

"log": "user3",

"pass": "password",

"nom": "Nom 3",

"email": "tes@test.com",

"quota": "11657",

"classe_domaines": "7"

}

]

Listes des pools d'IP disponibles

Cette fonction permet de récupérer la liste des pools d'IP attribués à votre compte principal.
Si vous disposez de plusieurs pools d'IP, vous pouvez choisir quel pool d'IP attribuer à vos sous-comptes.

Cette fonction permet de récupérer la liste des sous-comptes existant sous votre compte principal.

URL à utiliser : https://www.mdworks.fr/api_http/pools_list

Données à poster :

  • api_key : votre clé API

Exemple de données postées :

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"
}
Cette fonction retourne une chaine JSON contenant un tableau d'objets ayant cette structure :
  • id : ID unique du pool d'IP
  • nom : nom du pool d'IP
  • domaine_expediteur : nom de domaine de sender par défaut
  • domaine_tracking : nom de domaine pour le tracking des liens
  • ip_range : plage d'IP où sont situées les IP (pour vos SPF)
  • nb_ip : nombre d'IP disponibles
  • tracking_ssl : 1 si le certificat SSL est installé sur le domaine de tracking, 0 sinon
[

{

"id": "527",

"nom": "Classe 527 - Client XYZ - Premium MTA 101",

"domaine_expediteur": "domaine1.com",

"domaine_tracking": "domaine1.com",

"ip_range": "91.209.225.64/25",

"nb_ip": "2",

"tracking_ssl": "1"

},

{

"id": "545",

"nom": Classe 545 - Client XYZ - Premium MTA 101,

"domaine_expediteur": "domaine3.com",

"domaine_tracking": "domaine3.com",

"ip_range": "91.209.225.64/25",

"nb_ip": "2",

"tracking_ssl": "1"

}

]

Créer un sous-compte

Cette fonction permet de créer un sous-compte.
Le login du sous-compte doit être unique dans la base.

URL à utiliser : https://www.mdworks.fr/api_http/user_create

Données à poster :

  • api_key : votre clé API
  • log : login du sous-compte. Supérieur à 6 caractères et le plus spécifique possible (il doit être unique dans la base). Pas de caractères spéciaux ni n'accents.
  • pass : mot de passe supérieur à 8 caractères.
  • quota : quota d'envoi maximum (doit être inférieur au quota du compte principal)
  • nom : nom du sous-compte (affichage uniquement)
  • email : email du responsable technique du sous-compte. Cette adresse email reçoit les rapports de plaintes et les rapports de délisting. Utilisateur de la marque blanche : utilisez une adresse à vous pour que le client final ne reçoive pas de message d'Ediware.
  • pool_ip : ID du pool d'Ip à attribuer au sous-compte (cf. Listes des pools d'IP disponibles). Cette donnée est facultative, en cas d'absence, le pool d'IP du compte principal sera utilisé.

Exemple de données postées :

{

"api_key": "u6iph39pQ6yFx91OgsC0zqbzAexVG5JySQ9OryfG7HJ",

    "log": "user_test_new",

    "pass": "N5tkgGR8gCnsv3Dl7",

    "quota": "50"

}
Cette fonction retourne une chaine JSON contenant un tableau d'objets ayant cette structure :
  • user_id : ID unique du nouveau sous-compte
{

"user_id": "8458"

}

Supprimer un sous-compte

Attention un sous-compte ne peut-être supprimé que si aucune campagne n'a été envoyée.

URL à utiliser : https://www.mdworks.fr/api_http/user_delete

Données à poster :

  • api_key : votre clé API
  • user_id : l'uid du sous-compte à détruire (cf. liste des sous-comptes)

Exemple de données postées :

{

"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",

    "user_id": "4781"
}

Cette fonction retourne en cas de succès :

{"result": "ok"}

Modifier un sous-compte

URL à utiliser : https://www.mdworks.fr/api_http/user_update

Données à poster :

  • api_key : votre clé API
  • user_id : id du sous-compte à modifier
  • pass (inchangé si non présent) : mot de passe supérieur à 8 caractères.
  • quota (inchangé si non présent) : quota d'envoi maximum (doit être inférieur au quota du compte principal)
  • nom (inchangé si non présent) : nom du sous-compte (affichage uniquement)
  • email (inchangé si non présent) : email du responsable technique du sous-compte. Cette adresse email reçoit les rapports de plaintes et les rapports de délisting. Utilisateur de la marque blanche : utilisez une adresse à vous pour que le client final ne reçoive pas de message d'Ediware.
  • pool_ip (inchangé si non présent) : ID du pool d'Ip à attribuer au sous-compte (cf. Listes des pools d'IP disponibles). Cette donnée est facultative, en cas d'absence, le pool d'IP du compte principal sera utilisé.

Exemple de données postées :

{

"api_key": "u6iph39pQ6yFx91OgsC0zqbzAexVG5JySQ9OryfG7HJ",

    "user_id": "335",

    "quota": "45"

}

Cette fonction retourne en cas de succès :

{"result": "ok"}

Gestion des listes

Lister les listes d'un compte

Cette fonction retourne la liste des différentes listes de contacts pour un compte ou un sous-compte donné.

URL à utiliser : https://www.mdworks.fr/api_http/list_list

Données à poster :

  • api_key : votre clé API
  • user_id : uid du compte sur lequel créer la liste (cf. liste des sous-comptes). Si ce paramètres est manquant l'id du compte principal sera utilisée

Exemple de données postées :

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
 "user_id": "4781"
}

Cette fonction retourne un tableau d'objets :

[
{
"id": "254698",
"nom": "BASE_TEST_EDIWARE",
"field_email": "EMAIL",
"field_sms": "",
"total_lignes": "100868"
},
{
"id": "125478",
"nom": "Ma nouvelle liste",
"field_email": "EMAIL",
"field_sms": "",
"total_lignes": "254"
}
]

Créer une liste

Création d'une nouvelle liste pour un compte ou un sous-compte.

URL à utiliser : https://www.mdworks.fr/api_http/list_create

Données à poster :

  • api_key : votre clé API
  • user_id : uid du compte sur lequel créer la liste (cf. liste des sous-comptes). Si ce paramètre est manquant la liste sera placée sur le compte principal.
  • nom : nom de la liste
  • field_list : liste des champs séparés par des virgules (uniquement des lettres et le caractère "_"). Limité à 50 champs.
  • field_index : liste des champs sur lesquels la recherche doit être activée (les noms doivent être identiques à ceux utilisés pour field_list). Limité à 20 champs. Ce champ est facultatif.
  • field_email: nom du champ contenant les adresses email
  • email_crypt : facultatif. 0 par défaut. 1 pour que les adresses emails ne soient à aucun moment accessibles par l'utilisateur. Les adresses pourront par contre être exploitées dans le cadre de campagnes.

Exemple de données postées :

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
 "user_id": "4781",
"nom": "Ma nouvelle liste",
"field_list": "email,nom,prenom,civilite,societe,code_naf",
"field_index":"code_naf",
"field_email":"email"
}

Cette fonction retourne en cas de succès l'uid de la liste :

{"list_id": "33541"}

Voir la liste des champs d'une liste de contacts

Supprimer une liste

Création d'une nouvelle liste pour un compte ou un sous-compte.

URL à utiliser : https://www.mdworks.fr/api_http/list_delete

Données à poster :

  • api_key : votre clé API
  • list_id : uid de la liste à supprimer (cf. list_list)

Exemple de données postées :

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
 "list_id": "4781"
}

Cette fonction retourne en cas de succès :

{"result": "ok"}

Si la liste est protégée contre la suppression : "Error this list protected against delete, go to the dashboard"

Insérer des contacts dans une liste - méthode push

Insérer des contacts dans une liste pour un compte ou un sous-compte.

URL à utiliser : https://www.mdworks.fr/api_http/list_insert

Données à poster :

  • api_key : votre clé API
  • list_id : uid de la liste (cf. list_list).
  • tab_insert : un tableau de tableaux associatifs de données à insérer. Les clés du tableau doivent correspondre aux noms des champs. Leur ordre n'est pas important. Seul le champ contenant l'adresse email est obligatoire, les champs omis seront complétés par une valeur vide. Le nombre de ligne est limité à 255. Pour des raisons de performances nous vous conseillons d'éviter d'ajouter les lignes une par une.

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",  
"list_id": "4781",
"tab_insert":[{"email":"test@test.com","nom":"Dupont","prenom":"Martin","civilite":"Monsieur"},{"email":"test1@test.com","nom":"Durant","prenom":"Myrlène"}]
}

Exemple de variable en PHP :

$tab = array(
0 => array("email" => "test@test.com", "nom" => "Dupont", "prenom" => "Martin", "civilite" => "Monsieur"),
1 => array("email" => "test1@test.com", "nom" => "Durant", "prenom" => "Myrlène", "civilite" => "Madame")
);

En cas de succès la fonction retourne

{"result": "ok"}

Insérer des contacts dans une liste - méthode get

Cette méthode consiste à fournir à la plateforme une URL permettant de récupérer la liste de contacts.

Attention, nous vous conseillons de restreindre l'accès à cette page hébergée chez vous à nos IP.
Les IP que nous utiliserons pour interroger votre page sont les suivantes : 193.200.171.13 et 193.200.171.14

URL à utiliser : https://www.mdworks.fr/api_http/list_insert_url

Données à poster :

  • api_key : votre clé API
  • list_id : uid de la liste (cf. list_list).
  • url : L'url de la page contenant les données à insérer. Les données doivent être en CSV (séparateur point-virgule)

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",  
"list_id": "4781",
"url": "https://www.mdworks.fr/_tmp/maliste.csv"
}

Récupérer des statistiques de campagnes

Ces fonctions ne sont pas restreintes en terme d'IP car aucune données nominative n'est transmise.

Liste des campagnes et statistiques associées

Cette fonction retourne la liste des campagnes envoyées sur les 30 derniers jours pour un compte ainsi que l'ensemble de ses sous-comptes. Ainsi que les statistiques obtenues.
Il y a un cache pouvant aller jusqu'à une heure sur ces chiffres.

URL à utiliser : https://www.mdworks.fr/api_http_open/campaigns_stats

Données à poster :

  • api_key : votre clé API
  • list_id : uid de la liste (cf. list_list).
  • url : L'url de la page contenant les données à insérer. Les données doivent être en CSV (séparateur point-virgule)

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"  
}

Cette fonction retourne un tableau d'objets

[
{
"id": "688646",
"user_id" : "1474",
"user" : "compte1",
"reference": "Ma campagne test",
"subject": "TEST ENVOI 19:20",
"sent": "2021-02-10 19:26:01.000000",
"volume": "1300",
"open_unique": "260",
"open": "340",
"click_unique": "25",
"click": 50,
"hard_bounce": 10,
"soft_bounce": 4,
"unsubscribe": 2
},
{
"id": "688644",
"user_id": "1478",
"user": "compte2",
"reference": "Ma deuxième campagne test",
"subject": "TEST ENVOI",
"sent": "2021-02-10 19:05:15.000000",
"volume": "4151",
"open_unique": "1230",
"open": "1340",
"click_unique": "47",
"click": 75,
"hard_bounce": 5,
"soft_bounce": 0,
"unsubscribe": 30
}
]

Gestion des désinscriptions

Cette fonction est disponible pour ajouter des adresses à votre liste de désabonnements ou votre liste de radiation. Les adresses ajoutées à cette liste seront retirées automatiquement de tous les envois futurs à partir de votre compte.

Pour ajouter une adresse à la liste des désabonnés

URL à utiliser : https://www.mdworks.fr/api_http/unsub_add

Données à poster :

  • api_key : votre clé API
  • email : l'adresse email à désinscrire

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
"email": "emailadesabo@test.com"
}

Cette fonction retourne 1

{"result": "ok"}
Pour valider les tests, vous pouvez vérifier dans votre compte si l'adresse est bien prise en compte.
Attention, il y a un délai pouvant aller jusqu'à 10 minutes avant l'ajout à la liste repoussoir.

Pour ajouter une adresse à la liste de radiation

Si vous disposez d'un compte

URL à utiliser : https://www.mdworks.fr/api_http/unsub_global_add

Données à poster :

  • api_key : votre clé API
  • email : l'adresse email à désinscrire

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
"email": "emailadesabo@test.com"
}

Cette fonction retourne "ok"

{"result": "ok"}
Pour valider les tests, vous pouvez vérifier dans votre compte si l'adresse est bien prise en compte.