Documentation

Endpoint /check

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

Important: When implementing this email validation API, you should never send us your customer's full email. We only validate the domain, and where a full email is provided, we strip away the user part before processing the request.

Important: Due to sub-domains ( sub.test.com ) and multi-level country codes ( sub.test.co.uk ), you should split your email string using @ and send the full domain in your request.

URL

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

Headers

• Content-Type: application/json
• Authorization: Bearer {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.

{
  "domain": "host.com"
}

curl Example Request

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

Example Response

{
  "domain": "host.com",
  "score": 90, // Advised to block >= 75.
  "meta": {
    "block_list": false,
    "domain_age": 0,
    "website_resolves": false,
    "accepts_all_addresses": false,
    "valid_email_security": false,
    "forwarding": true
  }
}

Field Descriptions

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.
• 402 Payment Required : Your account has run out of lookups.
• 500 Internal Server Error : An error occurred on the server.

Good to know:

• invalid_domain_or_mx is returned when an invalid domain such as gmail.cim is provided or a mail server could not be found.
• error_processing_domain is returned when a domain could not be processed, or a malformed domain is provided.
• no_lookups_remaining is returned when your key has run out of lookups.

Ensure to handle these responses appropriately in your application.

Quota Endpoint

Retrieve your remaining lookup quota and overage settings. This is particularly useful and often used by larger customers who require programmatic tracking of usage.

URL

GET https://api.tempmaildetector.com/quota

Headers

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

curl Example Request

curl --request GET \
  --url https://api.tempmaildetector.com/quota \
  --header 'Authorization: Bearer {YOUR_API_KEY}'

Example Response

{
  "lookups_remaining": 150,
  "overage_enabled": true,
  "overage_count": 25,
  "overage_limit": 1000
}

Response Field Descriptions

Error Handling

• 200 OK : The request was successful.
• 401 Unauthorized : The API key is invalid or missing.

GDPR Statement

You should update your Terms of Service and GDPR statements outlining that you make use of Temp Mail Detector as a 3rd party Data Processor to manage email reputation and validation:

Our website uses TempMailDetector.com as a Data Processor to identify and block temporary or disposable email addresses during sign-up. This helps prevent abuse and is processed under our legitimate interest in maintaining service integrity (GDPR Art. 6(1)(f)).

WordPress Plugin

Our WordPress plugin automatically validates user email addresses during registration and checkout, blocking temporary and disposable email domains in real-time.

Features

• Blocklist — Enter your own list of domains to block
• Protect Comments — Choose if you would like the plugin to mark comments as spam
• Protect WooCommerce — Block temporary emails during WooCommerce checkout, customer registration, and account updates
• Plus Emails — Block emails which have a + in the user part
• External Check — This makes use of the live Temp Mail Detector database for real-time checks

Ghost Plugin

Automatically detect and remove members with temporary email addresses when they sign up to your Ghost publication. By configuring a member.added webhook, Ghost sends each new member to our endpoint where we score their email domain and optionally delete or disable the member via the Ghost Admin API if it looks disposable.

1. Connect Your Ghost Site

1. In your Ghost admin panel, go to Settings → Integrations → Add custom integration . Name it (e.g. "TempMailDetector") and copy the Admin API key .
2. In your TempMailDetector account settings → Plugins , enter your Ghost site URL and Admin API key, and choose what should happen when a disposable address is detected: delete the member (default) or unsubscribe them from all newsletters .

2. Configure Your Webhook

In the same Ghost custom integration, under Webhooks , add a new webhook with event Member added and the following target URL. Enter your TempMailDetector API key below to generate it.

Fill in your API key above to generate the URL.

Each new member is now checked on signup, and members with a disposable email address are handled automatically using the action you chose in your account settings.