The CheckMail API is a simple HTTP web service, that gives customers the ability to perform email address verification in real-time.

Use Cases

  • Integrate CheckMail into your account sign up process, to ensure the email address provided by the user is a valid, working email address. This way, you can avoid costly account creation processes, limit sign-ups by fake accounts, and keep your database clean.
  • Integrate CheckMail into your lead capture process, to filter out broken or low-qualify email addresses.
  • Integrate CheckMail into your marketing campaign process, to avoid needlessly sending emails to bad, broken, or misspelled address.

Applications

To begin using the CheckMail API, start first by creating an new Application from the Verify -> API Access section of the CheckMail portal. It’s recommended that you create one Application per integration. For example, if you intend to integrate the CheckMail API into your sign-up form, and a lead generation form, it’s recommended that you would set up two Application- one for each integration.

This lets you report on activity by Application, as well as revoke/change authentication credentials for one Application, without affecting the other. There is no limit on how many Applications you can create on your CheckMail account.

Simple Give the Application a name, and click the Add New Application button.

Once created, click on the Application Name to access the API credentials for this Application.

This Application can be disabled, or deleted at any time, by clicking the Status or Delete links on the Application.

Authentication

CheckMail uses HTTP basic authentication, using an Account SID and Auth Token, both available from the Verify -> API Access section of the CheckMail portal.

Both the Live and Test Auth Token can be regenerated at any time as needed.

Making a Request

The verification request should be a HTTP POST request to the URL:

https://api.checkmail.io/verify

To issue a verification request, you will need the following values:

ValueDescription
addressstring, required

The email address to be verified. This value should be URL encoded.
timeoutinteger, optional

The maximum time, in milliseconds, for the CheckMail API to complete a verification request. This gives you full control over the maximum amount of time you're willing to give CheckMail to complete the verification process.

Defaults to 5000 (5 seconds); Maximum value 30000 (30 seconds)

Getting the Response

A successful response will return a JSON object that looks something like this:

{
 "accept_all": false,
 "country_code": "US",
 "country_name": "United States",
 "disposable": false,
 "domain": "gmail.com",
 "email": "john.smith@gmail.com",
 "did_you_mean": "",
 "free": false,
 "localpart": "john.smith",
 "reason": "accepted_email",
 "result": "deliverable",
 "role": false,
 "social_media": false
}

For a full description of all the fields returned by the CheckMail API, view our Terminology section.

Response Headers

In addition to the response fields above, CheckMail will return the following HTTP response headers on each request:

Header NameDescription
X-CheckMail-Account-SIDstring

The Account SID matching your request. This will line up with the username portion of the HTTP basic authentication request.
X-CheckMail-Creditsinteger

The total number of remaining credits on your account.
X-CheckMail-Response-Timedecimal

The elapsed time it took CheckMail to process this verification request, in milliseconds.

API Limits

The CheckMail API is currently rate-limited to 10 simultaneous connections per account. If you think you’ll need a higher rate limit for your account, just let us know.

API Libraries

CheckMail includes several pre-built API libraries that can help you get up and running sooner. Currently have have libraries for PHP, Python, Ruby, and Node.js.

Libraries for Java, .Net, and GO will be coming soon.