Skip to content

API and Authentication

Check-Mail is an advanced API for detecting and blocking disposable and temporary email addresses. This guide will help you set up and start using the Check-Mail API quickly and effectively.

Prerequisites

Before you begin, ensure you have the following:

  • An active Check-Mail API account (available for free).
  • An API key. You can obtain this from your account dashboard once registered.
  • Basic understanding of HTTP requests.

Free Plan

We offer a free version of the API, which allows for 1000 lookups per month, no credit card required.

API Endpoint

The base URL for the Check-Mail API is:

https://api.check-mail.org/v1/

All API requests will be made to endpoints under this base URL.

Authentication

To authenticate requests, include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

The bearer API key can be base64 encoded, but doesn't have to be.

Example:

curl -X GET "https://api.check-mail.org/v1/?email=example@mail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Making Your First Request

Verify an Email Address

To check if an email address is disposable, make a GET request to / with the email address as a query parameter:

Endpoint:

GET /v1/?email=mail@example.com

Example Response:

{
  "valid": true,
  "block": true,
  "disposable": true,
  "domain": "temp-mail.org",
  "text": "Disposable / temporary domain",
  "reason": "Heuristics x6",
  "risk": 99,
  "mx_host": "mx.yandex.net",
  "possible_typo": [],
  "mx_ip": "77.88.21.249",
  "mx_info": "Using MX pointer mx.yandex.net from DNS with priority: 10",
  "last_changed_at": "2020-04-18T22:05:24+02:00"
}

The response will include information on whether the email is disposable, its domain, and if it is a valid format.

Response Codes

  • 200 OK: The request was successful.
  • 401 Unauthorized: Your API key is incorrect or missing.
  • 429 Too Many Requests: You have exceeded the monthly limits of you current plan (1000 for free per month).

Rate Limits

Your current plan's rate limit details can be found in your account dashboard. Free accounts can make 1000 requests per month.

If you exceed the rate limit, you will receive a 429 Too Many Requests status code.

Error Handling

The API returns the standard HTTP status codes to indicate the success or failure of your requests. Always check the response code to handle errors gracefully in your application.

Example of Error Response:

{
  "message":"Missing or invalid API auth"
}

Next Steps