Documentation

This is probably the world’s simplest serious REST based API.

You can use your browser to access URLs, and you can use pretty much any HTTP client in any programming language to interact with the API. All responses are formatted in JSON. You can send your requests via HTTP or HTTPS.

There is just one endpoint URL:

https://api.mailtest.in/v1/{ domain or subdomain }

Let’s try an example. Suppose your use case is a registration form where users are signing up to use your service. They enter a few details including their email address, hello@example.com. The domain (or subdomain) of the email address is everything to the right of the “@” sign.

Pass this to the MailTest API: Try it

https://api.mailtest.in/v1/example.com

In the is case, the result is as follows:

{
    "code": "23",
    "status": "INVALID",
    "message": "No MX Records Found"
 }

The status INVALID message tells us that there is a problem with this address and any email sent to that domain won’t reach an email inbox. In this circumstance, it is probably wise to ask your user for a new address as this one, even though it looks perfectly valid, isn’t actually working.

Status messages

Each response from our API will return one of six possible status messages. These are:

StatusDescription
ACTIVEThis domain is active and is set up to receive emails normally.
DISPOSABLEThis domain operates an anonymous, temporary or disposable email service (DEA). It is likely this inbox will only exist for a few minutes or hours.
ROBOTThis domain runs a monetized bounce service. Emails sent to this address will not be read by a human.
INVALIDThis domain is not setup to accept emails and any messages sent to it will bounce.
UNKNOWNMailTest has encountered a problem investigating this domain and cannot give a definitive answer at this time. How you handle this response depends on your use case but you may wish to treat the response as if it were active and optionally re-test at a later time.
ERRORMailTest encountered an error.

Testing

Use the following dummy subdomains to test API responses:

StatusSubdomainTry it
ACTIVEactive.mailtest.inTry it
DISPOSABLEdisposable.mailtest.inTry it
ROBOTrobot.mailtest.inTry it
INVALIDinvalid.mailtest.inTry it
UNKNOWNunknown.mailtest.inTry it
ERRORerror.mailtest.inTry it

Rate Limiting

The MailTest API uses the correct HTTP status codes. In the case where you exceed our request rate limit, you will receive an error message with the HTTP status code of 429. Please try again later or contact us to increase your limit.

Full response list

CodeStatusMessageHTTP Code
01ACTIVEOK200
11DISPOSABLEDisposable Email200
12ROBOTMonetized Bounce200
21INVALIDInvalid Domain200
22INVALIDUnregistered Domain200
23INVALIDNo MX Records Found200
81UNKNOWNWhois Lookup Error200
82UNKNOWNDNS Lookup Error200
91ERRORRate Limit Exceeded429
92ERRORInternal Server Error500

Integrating with your Website or App

We’re currently preparing a MailTest plugin for the Django Web Framework. We are also looking for open source developers to make similar plugins or add-ons for a range of other languages and platforms. If you would like to get involved we’d love to hear from you.