Manager

First send an email to yourusername-whateveryouwant[at]mail-tester.com (yourusername should be replaced by your own username!)

Then to use our API, call Mail-tester with this url:

https://www.mail-tester.com/yourusername-whateveryouwant&format=json

You can obviously replace "whateveryouwant" by everything you want... Please make sure it's an unique string so one test does not override another.

Basically, after calling this url, Mail-tester will process the mail sent to the given email address and return a JSON object than you can exploit.

Here is a short example of what you should execute to get the API result. This given example uses jQuery's function getJson but you can use whatever you prefer:

$.getJSON("https://www.mail-tester.com/aaweb-pDrqwp&format=json", function(data){
  if(data.status==false){
    document.write(data.title);
    return;
  }
  $.each(data, function(key, value){
	document.write(key+": "+value+"<br/>"); 
  });
});
		

If you don't want to waste time performing tests you don't need, you can add &test=key to get only specific tests. key must be replaced by one of our 5 main tests that are described in the structure part (for example &test=signature).

Also note that you can add &lang=fr-fr (for example) if you want to change the language.

Back to top

Since Mail-Tester is providing a lot of information and we don't want you to be lost, we added a little that developers will love.

If you replace &format=json by &format=dbug, you will indeed be able to visualize everything we return concerning your newsletter through a flexible interface. Want an example? Check this out!

With this visualization, you can also click on the name of the variables (for example spamAssassin), to hide or display this part of the object. You can thus focus on certain aspects of the object that interest you. I told you, you're gonna love this.

Note that this feature uses dBug.php, a free tool that you can download here

Back to top

As you may have noticed, Mail-Tester provides quite a lot of information about your emails. Well the API includes everything on the result page and even more.

Since we have implemented dBug in our API, the best way to have a good vision of what the API returns is to look at an example processed with dBug. So here is the result for one of our fabulous mail.

If the variables' name are not clear enough for you, you can still take a look at our short sum-up about it.

Structure

Six main sub-objects can be identified inside the main object. These sub-object are the same as the main categories on a classic Mail-Tester result page:

• Main object: Contain the main information about the test such as the id of the address you mailed, the final score and our short comment about it.
• messageInfo: This sub-object contain few information about the message itself such as the subject, the reception date (MySQL format) and the bounce Address.
• spamAssassin: You will find here every information related to the spamAssassin test. The most interesting is the array rule which includes every notable test made by spamAssassin with the code, the score and our suggestions.
• signature: This one is a big one! It includes every authentification test as SPF, SenderId, DKIM and rDNS. You should find here every information related to these methods, including score, comments and suggestions.
• body: Here you can find multiple version of your email (HTML, Text, raw version) as well as the results of our tests on the boby like the HTML to text ratio, the forbidden tags or the alt attributes.
• blacklists: This object contain an array with every blacklist we tested and the answer for your newsletter.
• links: This last one gives you the broken links we found.

More generally, you will almost always find these variables inside of any variable related to a test (such as spf, texToHtmlRatio or blacklists):

• title: The title sums up the test, telling you what's good or wrong for this specific test.
• mark: The mark you got for this specific test, always less than or equal to 0.
• displayedMark: The mark we actually display. If it is superior or equal to zero, we replace it by &#10003 to display something nice.
• status: The status of the test
• statusClass: The name of the class we use for our own design. Either failure, warning, neutral or success.
• description: A short description of the test itself.
• messages: A HTML formatted message with our suggestions about the test and it results.

Errors

If, for any reason, the Mail-tester test didn't work, you will still receive a formatted object in json or with a dBug. The variable $object->status should then be false and $object->title will give you an error message.

Back to top