Documentation
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:
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.
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. |