This page documents the use of the REST API functions.

Only the main features are available. Some functions are only available in the SOAP API.
Data must be submitted in UTF-8 if it contains special characters or accents.

Account setup

Retrieve the REST API key

In your account, go to the Account Management page > API / Zapier > Key for REST API and Zapier
and request an API key if the function is not yet activated.

Declare your IP

Declare the IPs of your applications that will access the REST API, separated by commas.

Authentication to the REST API is done using both the IP of the machine querying the API and the API key.

Except for functions where the access point is in https://www.mdworks.fr/api_http_open/...
These display or statistics functions are open from any IP.

Error management

In case of error, the API returns a string in JSON format with the error details:

{

"error": "1",

"message": "Error api_key invalid"

}

Example of code in 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);

User management

List of sub-accounts

This function allows you to retrieve the list of sub-accounts existing under your main account.

URL to use: https://www.mdworks.fr/api_http/user_list

Data to be posted:

  • api_key : your API key

Example of posted data:

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"
}
This function returns a JSON string containing an array of objects with this structure :
  • id : unique ID of the sub-account
  • log : unique login of the sub-account
  • pass: password of the sub-account
  • name: name of the sub-account (optional, used for display)
  • email: email of the technical contact of the sub-account (used to send complaint reports and delisting reports)
  • quota : sending quota assigned to the sub-account
  • class_domains : id of the IP pool assigned to the sub-account (see list of available IP pools)
[

{

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

}

]

Lists of available IP pools

This function allows you to retrieve the list of IP pools assigned to your main account.
If you have several IP pools, you can choose which IP pool to assign to your sub-accounts.

This function allows you to retrieve the list of sub-accounts existing under your main account.

URL to use: https://www.mdworks.fr/api_http/pools_list

Data to be posted:

  • api_key : your API key

Example of posted data:

{
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"
}
This function returns a JSON string containing an array of objects with this structure :
  • id : unique ID of the IP pool
  • name: name of the IP pool
  • sender_domain: default sender domain name
  • domain_tracking : domain name for tracking links
  • ip_range : IP range where the IPs are located (for your SPF)
  • nb_ip : number of available IP
  • tracking_ssl : 1 if the SSL certificate is installed on the tracking domain, 0 otherwise
[

{

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

}

]

Create a sub-account

This function allows you to create a sub-account.
The sub-account login must be unique in the database.

URL to use: https://www.mdworks.fr/api_http/user_create

Data to be posted:

  • api_key : your API key
  • log : login of the sub-account. More than 6 characters and as specific as possible (it must be unique in the database). No special characters or accents.
  • pass: password greater than 8 characters.
  • quota: maximum sending quota (must be lower than the quota of the main account)
  • name: name of the sub-account (display only)
  • email : email of the technical manager of the sub-account. This email address receives complaint reports and delisting reports. White label user: use an address of your own so that the end customer does not receive any message from Ediware.
  • pool_ip : ID of the IP pool to assign to the sub-account (see Lists of available IP pools). This data is optional, in case of absence, the IP pool of the main account will be used.

Example of posted data:

{

"api_key": "u6iph39pQ6yFx91OgsC0zqbzAexVG5JySQ9OryfG7HJ",

    "log": "user_test_new",

    "pass": "N5tkgGR8gCnsv3Dl7",

    "quota": "50"

}
This function returns a JSON string containing an array of objects with this structure :
  • user_id : unique ID of the new sub-account
{

"user_id": "8458"

}

Delete a sub-account

Attention a sub-account can only be deleted if no campaign has been sent.

URL to use: https://www.mdworks.fr/api_http/user_delete

Data to be posted:

  • api_key : your API key
  • user_id : the uid of the sub-account to destroy (see sub-account list)

Example of posted data:

{

"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3",

    "user_id": "4781"
}

This function returns in case of success :

{"result": "ok"}

Modify a sub-account

URL to use: https://www.mdworks.fr/api_http/user_update

Data to be posted:

  • api_key : your API key
  • user_id : id of the sub-account to modify
  • pass (unchanged if not present): password greater than 8 characters.
  • quota (unchanged if not present) : maximum sending quota (must be lower than the quota of the main account)
  • name (unchanged if not present) : name of the sub-account (display only)
  • email (unchanged if not present): email of the technical manager of the sub-account. This email address receives complaint reports and delisting reports. White label user: use your own address so that the end customer does not receive messages from Ediware.
  • pool_ip (unchanged if not present): ID of the IP pool to assign to the sub-account (see Lists of available IP pools). This data is optional, in case of absence, the IP pool of the main account will be used.

Example of posted data:

{

"api_key": "u6iph39pQ6yFx91OgsC0zqbzAexVG5JySQ9OryfG7HJ",

    "user_id": "335",

    "quota": "45"

}

This function returns in case of success :

{"result": "ok"}

List management

List the lists of an account

This function returns a list of the different contact lists for a given account or sub-account.

URL to use: https://www.mdworks.fr/api_http/list_list

Data to be posted:

  • api_key : your API key
  • user_id: uid of the account on which to create the list (see list of sub-accounts). If this parameter is missing the main account id will be used

Example of posted data:

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

This function returns an array of objects:

[
{
"id": "254698",
"nom": "BASE_TEST_EDIWARE",
"field_email": "EMAIL",
"field_sms": "",
"total_lignes": "100868"
},
{
"id": "125478",
"name": "My new list",
"field_email": "EMAIL",
"field_sms": "",
"total_lines": "254"
}
]

Create a list

Create a new list for an account or a sub-account.

URL to use: https://www.mdworks.fr/api_http/list_create

Data to be posted:

  • api_key : your API key
  • user_id: uid of the account on which to create the list (see list of sub-accounts). If this parameter is missing the list will be placed on the main account.
  • name: name of the list
  • field_list: comma separated list of fields (only letters and the character "_"). Limited to 50 fields.
  • field_index : list of fields on which the search must be activated (the names must be identical to those used for field_list). Limited to 20 fields. This field is optional.
  • field_email: name of the field containing the email addresses
  • email_crypt: optional. 0 by default. 1 so that the email addresses are not accessible by the user at any time. However, the addresses can be used for campaigns.

Example of posted data:

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

This function returns in case of success the uid of the list:

{"list_id": "33541"}

See the list of fields in a contact list

Delete a list

Create a new list for an account or a sub-account.

URL to use: https://www.mdworks.fr/api_http/list_delete

Data to be posted:

  • api_key : your API key
  • list_id : uid of the list to delete (cf. list_list)

Example of posted data:

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

This function returns in case of success :

{"result": "ok"}

If the list is protected against deletion: "Error this list protected against delete, go to the dashboard".

Inserting contacts into a list - push method

Insert contacts in a list for an account or a sub-account.

URL to use: https://www.mdworks.fr/api_http/list_insert

Data to be posted:

  • api_key : your API key
  • list_id : uid of the list (cf. list_list).
  • tab_insert: an array of associative data tables to insert. The keys of the table must match the names of the fields. Their order is not important. Only the field containing the email address is mandatory, the omitted fields will be filled with an empty value. The number of lines is limited to 255. For performance reasons we advise you to avoid adding the lines one by one.

Example of posted data:

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

Example of a variable in 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")
);

In case of success the function returns

{"result": "ok"}

Inserting contacts into a list - get method

This method consists in providing the platform with a URL to retrieve the contact list.

Please note that we advise you to restrict access to this page hosted on your site to our IPs.
The IPs we will use to query your page are 193.200.171.13 and 193.200.171.14

URL to use: https://www.mdworks.fr/api_http/list_insert_url

Data to be posted:

  • api_key : your API key
  • list_id : uid of the list (cf. list_list).
  • url: The url of the page containing the data to insert. Data must be in CSV (semicolon separator)

Example of posted data:

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

Retrieve campaign statistics

These functions are not restricted in terms of IP because no nominative data is transmitted.

List of campaigns and associated statistics

This function returns the list of campaigns sent over the last 30 days for an account and all its sub-accounts. As well as the statistics obtained.
There is a cache of up to one hour on these numbers.

URL to use: https://www.mdworks.fr/api_http_open/campaigns_stats

Data to be posted:

  • api_key : your API key
  • list_id : uid of the list (cf. list_list).
  • url: The url of the page containing the data to insert. Data must be in CSV (semicolon separator)

Example of posted data:

{ 
"api_key": "BAuIX9pb2CwSr9p0cyJoOfNMnxQ1dAUxfY5nwpL6Dh3"  
}

This function returns an array of objects

[
{
"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
}
]

Unsubscribe management

This feature is available to add addresses to your unsubscribe or delist list. Addresses added to this list will be automatically removed from all future mailings from your account.

To add an address to the unsubscribed list

URL to use: https://www.mdworks.fr/api_http/unsub_add

Data to be posted:

  • api_key : your API key
  • email : the email address to unsubscribe

Example of posted data:

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

This function returns 1

{"result": "ok"}
To validate the tests, you can check in your account if the address is taken into account.
Please note that there is a delay of up to 10 minutes before the list is added to the reject list.

To add an address to the delisting list

If you have an account

URL to use: https://www.mdworks.fr/api_http/unsub_global_add

Data to be posted:

  • api_key : your API key
  • email : the email address to unsubscribe

Example of posted data:

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

This function returns "ok".

{"result": "ok"}
To validate the tests, you can check in your account if the address is taken into account.

This post is also available in: Français (French)