Documentation

Here you can read the Documentation of Mailsguide Email Validation and Verification REST API.

API access Key and Authentication

After signing up, you will get an API key which will be your unique authentication key to access Mailsguide API.

Authentication is done via HTTP Bearer Auth Token in the header. To connect you have to include a header in each of your requests with the following key-value pair:

“Authorization”: “Bearer <your API key>”

				
					const request = require("request");

const options = {
  method: "POST",
  url: "https://api.mailsguide.com",
  headers: {
	"Content-Type": "application/json",
	"Authorization": "Bearer YOUR-API-KEY"
  },
  body: {},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

HTTPS encryption

In order to connect to our API securely, please use industry-standard HTTPS (SSL) encryption. To connect via HTTPS, make sure you use https protocol in your API request.

Rate limits

Requests to the API are rate limited based on your current subscription plan:

Basic Plan: 3 requests / second
Standard Plan: 10 requests / second
Pro Plan: 30 requests / second

Email Validation API Request Parameters

To validate an email you will only need two parameters:

Your API key in the API request header
The email adress you want to validate in the API request body with the following key-value pair:

“email_adress”: “example@domain.com”

				
					const request = require("request");

const options = {
  method: "POST",
  url: "https://api.mailsguide.com",
  headers: {
	"Content-Type": "application/json",
	"Authorization": "Bearer YOUR-API-KEY"
  },
  body: {
    "email_adress": "example@domain.com"
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Checking Multiple Email Adresses

Mailsguide API allows you to check multiple email adresses at the same time. To do so, simply add the email addresses to the API request body separated by comma.

				
					  body: {
    "email_adress": "example@domain.com, example2@domain.com, example3@domain.com..."
  }

The Response

A succesful API request returns the following parameters:

email	The requested email adress
autocorrect	If the API found a typo, you will get a suggestion of the correct email
valid_format	Returns true if the format is : address @ domain . TLD
mx_found	Returns true if MX Records for the domain can be found.
smtp_check	Returns true if the SMTP check of the domain was successful.
catch_all	Returns true if the requested email address is found to be part of a catch-all mailbox
role	Returns true if if the email's local part (e.g., the "to" part) appears to be for a role rather than individual
free	Returns true if the requested email address is a free email address (gmail, yahoo..)
disposable	Returns true if the email's domain is found among Mailsguide's list of disposable email providers
score	Returns a score between 0 and 1 reflecting the quality and deliverability of the email address

Valid_format

The structure of an email address is comprised of two parts: the local-part (up to 64 characters) and the domain (up to 253 characters), separated by the “@” symbol. (local-part@domain)

Local part:

Up to 64 characters long
Uppercase and lowercase Latin letters (A–Z, a–z) (ASCII: 65–90, 97–122)
Digits 0 to 9 (ASCII: 48–57)

These special characters: # – _ ~ ! $ & ‘ ( ) * + , ; = : and percentile encoding i.e. %40
Character . (dot, period, full stop), ASCII 46, provided that it is not the first or last character, and provided also that it does not appear consecutively

Domain part:

It must match the requirements for a hostname, consisting of letters, digits, hyphens and dots. The domain part may be an IP address literal, surrounded by square braces. (rare, mostly spam)

Autocorrect

MailsGuide API checks for potential typos or misspellings in the domain part of the requested email address. If detected, it provides an alternative email suggestion in the “autocorrect” object of the API result set.

Mx_found, smpt_check

Mailsguide API verifies email addresses by checking MX records and the use of SMTP (Simple Mail Transfer Protocol), the standard protocol for email transfer.

The email verification process begins by determining if the requested domain is set up to receive email. If MX-Records are found, the API returns “true” in the “mx_found” response object.

Then, the assigned mail server for the requested email address is reached through SMTP. The SMTP conversation that follows is the key factor in determining the existence of the provided email address.

The API response’s “smtp_check” JSON object indicates the success of the SMTP check with a “true” or “false” value.

Catch_all

A catch-all detection function has been integrated to address the common configuration of email servers to receive all incoming mail, regardless of the local part of the requested email address.

The API response’s “catch_all” JSON object indicates if the requested email address is part of a catch-all mailbox with a “true” or “false” value.

Role

Points to a specific function, such as “support” or “marketing” rather than an individual or name. Sending email campaigns to role email addresses can be ineffective as they often result in low open rates.

The API response’s “role” JSON object indicates if the requested email is a role address with a “true” or “false” value.

Free

MailsGuide is connected to a database that is updated daily and contains all available email providers, enabling it to identify popular free services like Gmail and Yahoo!. The API response’s “free” JSON object returns a “true” or “false” value depending on whether the requested email address uses a free service.

Disposable

Disposable emails are temporary and will only be valid for a short period of time.They are often created by users who do not wish to give their primary address.

The API will also indicate if the requested email address uses a disposable email provider with a “true” or “false” value in the “disposable” JSON object.

Score

The API provides a numeric “Quality Score” ranging from 0 (Bad) to 1 (Good) that reflects the quality and deliverability of the requested email address.

The API focuses on evaluating three main factors:

Appearance: How similar the local or domain part of the email address is to high-quality email addresses.
Deliverability: Whether the email syntax is valid and the SMTP check confirms the existence of the requested email address.
Background: Whether the requested email address is linked to a free or disposable email provider or points to a role.

Note: The Quality Score is just a guide and should not be the sole determinant in deciding whether to send to an email address.

API errors

If your request to the API did not succeed, you get an error response with a 3-digit code.Look it up on this page to see what it means.

400 Bad Request	Bad request
401 Unauthorized	Invalid or not specified license key
429 Too Many Requests	You have overrun a usage limit for your plan
500 Internal Server Error	The request could not be completed due to an error on the server side.
504 Time Exceeded	An unexpected timeout issue occurred.