API Documentation

Learn how to integrate MailCheck's email verification API into your applications.

Introduction

What is MailCheck?

A powerful email verification service to improve data quality and reduce fraud.

MailCheck is an advanced email verification API that helps businesses validate email addresses in real-time. Our service goes beyond simple syntax checks to ensure you collect only high-quality, deliverable email addresses.

Prevent Fraud

Identify and block disposable email addresses and detect fraudulent sign-up attempts.

Improve Deliverability

Ensure emails reach real inboxes by validating domain records and mailbox existence.

Our API offers multiple verification methods to balance between speed, accuracy, and user experience depending on your specific needs.

Getting Started

Base URL

All API requests should be made to the following base URL:

https://api.mail-check.tech

Authentication

All API requests require an API key to be included in the request headers.

Include your API key in the X-API-Key header:

X-API-Key: your_api_key_here

You can find your API key in the Dashboard.

Understanding Verification Methods

S1 vs TBA Verification

MailCheck offers two levels of email verification to meet different needs.

S1 Verification

Standard verification that checks email syntax, domain validity, digging into the records associated with the domain, Analysing domain usages apart from email and compares against our database of known disposable email providers. This is suitable for most applications and provides a good balance between accuracy and speed.

Fast response times
No user interaction required
Consumes 1 credit per verification
Recommended for sign-up forms and bulk verification

TBA Verification (Task-Based Authentication)

Advanced verification that includes all S1 checks plus additional behavioral analysis and task-based verification. This provides the highest level of certainty about an email's validity.

Higher accuracy in detecting sophisticated fraud attempts
May require additional processing time
Consumes 1 credits per verification
Recommended when needs_TBA is true from an S1 verification

Recommended Workflow:

Start with S1 verification for all email addresses
If is_valid is true and needs_TBA is false, accept the email
If is_valid is false, and needs_TBA is false, reject the email
If needs_TBA is true, perform a TBA verification for higher certainty

API Endpoints

S1 Verification

Verify an email address using standard verification methods.

Endpoint

POST /api/v0/validate/email

Request

curl -X POST https://api.mail-check.tech/api/v0/validate/email \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"email": "user@example.com"}'

Response

{
  "is_valid": true,
  "needs_TBA": false,
  "reason": "Domain has valid MX records and passes all verification checks"
}

Response Parameters

Parameter	Type	Description
is_valid	boolean	Indicates whether the email is legitimate or not
needs_TBA	boolean	Indicates whether a Task-Based Authentication check should be performed for higher certainty
reason	string	Explains why the domain was marked as legitimate or as a temporary email

TBA Verification

Verify an email address using Task-Based Authentication (TBA) methods.

Endpoint

POST /api/v0/validate/email/tba

Request

curl -X POST https://api.mail-check.tech/api/v0/validate/email/tba \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{"email": "user@example.com"}'

Response

{
  "is_valid": true,
  "needs_TBA": false,
  "reason": "Email passed Task-Based Authentication verification"
}

Response Parameters

Parameter	Type	Description
is_valid	boolean	Indicates whether the email is legitimate or not
needs_TBA	boolean	Indicates whether a Task-Based Authentication check should be performed for higher certainty
reason	string	Explains why the domain was marked as legitimate or as a temporary email

Error Handling

Error Responses

The API returns standard HTTP status codes and JSON error messages.

Example Error Response

{
  "detail": "API key missing. Please provide a valid API key in the X-API-Key header."
}

Common Error Codes

Status Code	Description
401	Unauthorized - Missing or invalid API key
403	Forbidden - The API key doesn't have permission to perform the request
422	Unprocessable Entity - The request was malformed or missing required parameters
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong on our end