Temp Mail Detector API Documentation

Overview

The TempMailDetector API allows website owners to check if an email host is a temporary or disposable email provider. This API is useful for applications that need to ensure email addresses provided by users are valid and not temporary.

The API is designed to respond in a “default open” fashion. Where a decision can not be made, the API will lean towards emails not being marked as temporary.

Important: When using the Temp Mail Detector service, your users emails should never be sent to us. We only validate the host, and where a full email is provided, strip away the user - also known as the “local-part” - and only process the host.

Endpoint /check

Checks if an email address is a temporary or disposable email address.

URL

POST https://api.tempmaildetector.com/check

Headers

• Content-Type: application/json
• Authorization: {YOUR_API_KEY}

Request Body

The request body should be in JSON format and contain the following parameter:

• domain (string, required): The domain (also known as the host) of the email address to be checked.

Example Payload

{
  "domain": "host.com"
}

cURL Example

curl --request POST \
  --url https://api.tempmaildetector.com/check \
  --header 'Content-Type: application/json' \
  --header 'Authorization: {YOUR_API_KEY}' \
  --data '{"domain":"host.com"}'

Response

The response will be in JSON format and contain the following fields:

• domain (string): The email domain that was checked.
• score (integer): The score indicating the likelihood of the email domain being associated with temporary emails (higher score means higher likelihood).
• meta (object): An object containing additional metadata about the email domain.

Meta Object

• block_list (boolean): Indicates if the email domain is in a block list.
• domain_age (integer): The age of the email domain in years. -1 indicates that a WHOIS response was not possible.
• website_resolves (boolean): Indicates if the email domain has a resolvable website.
• accepts_all_addresses (boolean): Indicates if the email domain accepts any random email addresses.
• valid_email_security (boolean): Indicates if the email domain has valid email security measures.

Example Response

{
  "domain": "host.com",
  "score": 90,
  "meta": {
    "block_list": false,
    "domain_age": 0,
    "website_resolves": false,
    "accepts_all_addresses": false,
    "valid_email_security": false
  }
}

Field Descriptions

domain

Type: string

The email domain that was checked.

---

score

Type: integer

A score from 0 to 100 indicating the likelihood of the email domain being associated with temporary emails. A higher score means a higher likelihood.

---

meta

Type: object

An object containing additional metadata about the email domain.

---

meta.block_list

Type: boolean

Indicates if the email domain is in a block list. true means the domain is in our block list and should be treated as a definite temporary email provider.

---

meta.domain_age

Type: integer

The age of the email domain in years. A lower number might indicate a recently created domain often used for temporary emails. A value of -1 indicates that we were unable to obtain a creation date from the WHOIS registry.

---

meta.website_resolves

Type: boolean

Indicates if the email domain has a resolvable website. true means the domain has a resolvable website. Many temporary email providers use domains which do not resolve, thus false is an indicator to suggest the domain is a temporary mail.

---

meta.accepts_all_addresses

Type: boolean

Indicates if the email domain accepts all email addresses. true means the domain accepts any email address, a common trait of temporary email providers.

---

meta.valid_email_security

Type: boolean

Indicates if the email domain has valid email security measures. true means the domain has valid security measures, while false indicates otherwise.

---

Error Handling

The API will return appropriate HTTP status codes to indicate success or failure of the request. Common status codes include:

• 200 OK: The request was successful.
• 400 Bad Request: The request was malformed or missing required parameters.
• 401 Unauthorized: The API key provided is invalid or missing.
• 500 Internal Server Error: An error occurred on the server.

Ensure to handle these responses appropriately in your application.