API Documentation

DEPRECATED! Verimail v1 is deprecated. It was replaced by v3 on October 2019. Check v3 documentation instead.

INTRODUCTION

Verimail is a REST based JSON API.

It provides a stateless endpoint that any program or web browser can call by sending a standard HTTP request. Verimail will respond with a standard HTTP response carrying a JSON payload. This documentation describes the endpoint, its input/output parameters and authentication methods.

AUTHENTICATION

Verimail supports two authentication methods, key based and domain based authentication.

Key Based Authentication

Verimail will respond to requests carrying the HTTP parameter key. The key parameter must contain a 32-character chain that registered users can copy from their control panel.

Example 
https://api.verimail.io/v1/verify?key=712E59151C8B4D1DB593D43678ABBF47
Domain Based Authentication

Verimail will allow all requests coming from authorized domains. You can authorize your domain on your control panel.

ERRORS

verimail uses standard HTTP status codes to indicate the success or failure of a request. Successful requests will receive a 200 response code, while responses with a 40x or 500 indicate a failure.

400
Bad request		 Returned if a required input parameter is missing.
401
Unauthorized		 Returned if the request is coming from an unauthorized domain and the key parameter is missing or not valid.
403
Forbiden		 Indicates that the key or domain used is inactive. This usually happens if a usage quota is exceeded or a payment is overdue.
500
Server error		 Internal server error. Indicates a failure on verimail servers. Although these are rare, if you get one please report it here

VERIFY

The verify endpoint takes an email address as input and tells you:

  • if it has a valid format
  • if the corresponding domain has valid MX records
  • if it is a generic role address (like 'admin' or 'support')
  • if it is a disposable or temporary address

It will also detect typos for most free email providers (like gmail, yahoo, outlook) and suggest a correction.

It is meant to be fast, reliable and affordable enough to be used for real-time validation. Meaning you can validate email addresses as your users are typing them on your form. That's why verify will not do SMTP check on email addresses, as SMTP checks are often slow, expensive and not guaranteed to work.

URL
https://api.verimail.io/v1/verify
Method GET POST
Input
key
String		 Authentication key
(optional if sent from an authorized domain)
email
String		 An email address
Output
status
String		 Status indicating the success or failure of the request execution. Values: success, error
email
String		 The email address provided as input
email_valid
true/false		 True if the email address format is valid and the domain has valid MX records.
user
String		 The user part of the email address provided
domain
String		 The domain part of the email address provided
domain_valid
true/false		 True if the domain has valid MX records.
role
true/false		 True if the email address provided is a generic role address (contact, info, sales, support…)
disposable
true/false		 True if the email address provided is temporary or disposable
did_you_mean
String		 If a common typo is detected, a correction is suggested here.
Request
https://api.verimail.io/v1/verify?email=support@verimail.io&key=712E59151C8B4D1DB593D43678ABBF47
Response
{
  "status": "success",
  "email": "support@verimail.io",
  "email_valid": true,
  "user": "support",
  "domain": "verimail.io",
  "domain_valid": true,
  "role": true,
  "disposable": false,
  "did_you_mean": ""
}