Documentation

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

Documentation

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:

emailThe requested email adress
autocorrectIf the API found a typo, you will get a suggestion of the correct email
valid_formatReturns true if the format is : address @ domain . TLD
mx_foundReturns true if MX Records for the domain can be found.

smtp_checkReturns true if the SMTP check of the domain was successful.
catch_allReturns true if the requested email address is found to be part of a catch-all mailbox
roleReturns true if if the email's local part (e.g., the "to" part) appears to be for a role rather than individual
freeReturns true if the requested email address is a free email address (gmail, yahoo..)
disposableReturns true if the email's domain is found among Mailsguide's list of disposable email providers
scoreReturns 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:

  1. Appearance: How similar the local or domain part of the email address is to high-quality email addresses.

  2. Deliverability: Whether the email syntax is valid and the SMTP check confirms the existence of the requested email address.

  3. 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 RequestBad request
401 UnauthorizedInvalid or not specified license key
429 Too Many RequestsYou have overrun a usage limit for your plan
500 Internal Server ErrorThe request could not be completed due to an error on the server side.
504 Time Exceeded
An unexpected timeout issue occurred.
Scroll to Top