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"
}

• 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"

}

]

Récupérer l'API Key d'un sous-compte

Cette fonction permet de récupérer d'un sous-compte existant sous votre compte principal.

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

Données à poster :

• api_key : votre clé API
• user_id : l'id du sous-compte

Exemple de données postées :

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

• user_id : ID unique du sous-compte
• api_key : sa clé API. S'il n'y en avait pas, elle est créée

{

"user_id": 33,

"api_key": "yYv1k03mUNDhSF3XLQTdJEuYUAsAtMtW7dsfU4LXv1xcabBqfPu04iA2MtzkIWE3",

}

Listes des pools d'IP disponibles

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"
}

[

{

"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 : le nom de l'expéditeur par défaut (peut-être vide)
• email : l'email de l'expéditeur par défaut (peut-être vide)
• 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"

}

• 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"

}

{"result": "ok"}

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

{"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"
},

]

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"
}

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

Cette fonction permet d'insérer les nouveaux contacts et de modifier les contacts existants dans une liste pour un compte ou un sous-compte.
Privilégiez la fonction d'insertion seule s'il n'y a pas de modifications à gérer, car la fonction list_insert_or_update est plus lente (une vérification d'existence est effectuée pour chaque ligne).

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

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.
• index_key : le nom du champ sur lequel doit se faire la recherche pour savoir s'il s'agit d'un nouveau contact ou d'un contact à modifier. ATTENTION, ce champ doit avoir le paramètre "unicité" activé dans l'interface sinon une erreur sera retournée (afin de ne pas compromettre les données existantes).

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"}],
"index_key" : "email"
}

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"}

Injecter un segment d'une liste de contacts dans une campagne

Cette fonction permet d'injecter un extrait d'une liste de contacts dans une campagne.
La liste de contact doit être accessible pour l'utilisateur (il doit soit en être le propriétaire, soit être dans la liste des utilisateurs avec qui elle est partagée).

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

Données à porter :

• api_key : votre clé API
• list_id : uid de la liste (cf. list_list).
• campaign_id : uid de la campagne.
• filter : un tableau de clés / valeurs encodé en JSON (la clé étant un champ et la valeur la chaîne de caractères à rechercher). Utilisez un tableau vide pour injecter toute la liste.

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",  
"list_id": "4781",
"campaign_id" : "784541",
"filter":"{\"NAF_700\":\"0111Z\",\"EFFECTIF\":0}
}

Exemple de variable en PHP :

$filter = json_encode(array('NAF_700' => '0111Z', 'EFFECTIF' => 0));

En cas de succès la fonction retourne

{"result": "ok"}

Vérifier que l'import de contacts dans une campagne est terminé

Cette fonction permet de savoir si l'import de contact dans une campagne est fini.
La liste de contact doit être accessible pour l'utilisateur (il doit soit en être le propriétaire, soit être dans la liste des utilisateurs avec qui elle est partagée).

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

Données à porter :

• api_key : votre clé API
• campaign_id : uid de la campagne.

Exemple de données postées :

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",  
"campaign_id" : "784541",
}

Si l'import est terminé, la fonction retourne le nombre de contacts :

{"result": 42053}

sinon :

{"result": running}

Récupérer des informations de campagnes

Liste des campagnes et statistiques associées

Cette fonction n'est pas restreinte en terme d'IP car aucune données nominative n'est transmise.

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
}
]

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
"campaign_id": "234433" 
}

[
{
"email" : "test@test.com",
"status" : "empty",
"bounceCat": "",
"dsnMta": "mx3.ovh.net (91.121.56.64)",
"dsnDiag": "smtp;250 2.0.0 Ok: queued as 4Stsl60YVKz1xxl",
},
{
"email" : "test3@test5.com",
"status" : "hard_bounce",
"bounceCat": "bad-domain",
"dsnMta": "",
"dsnDiag": "bad destination system: no such domain",
"timeLogged" :"2023-10-22 15:01:21"
}
]

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",
"campaign_id": "234433" 
}

[
{
"date" : "2024-02-19",
"email" : "test@test.com",
"raison": "npai",
},
{
"date" : "2024-02-19",
"email" : "test2.test.com",
"raison": "desabo",
}
]

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

{"result": "ok"}

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

{"result": "ok"}

This post is also available in: English (Anglais)