Mailchk

Documentation

API Documentation

Integrate disposable email detection into your application with our simple REST API.

Email ValidationEmail TestingSMS Testing

Quick Start

curl -X GET "https://api.mailchk.io/v1/check?email=test@example.com"

Base URL

https://api.mailchk.io

Authentication

All API requests must be authenticated using an API key. Include your API key in the x-api-key header with every request.

Getting Your API Key

  1. 1.Sign up for a free account at mailchk.io/signup
  2. 2.Go to your Dashboard → API Keys
  3. 3.Click "Create API Key" to generate a new key
  4. 4.Copy your key and store it securely (you won't be able to see it again)

Keep your API keys secure

Never expose API keys in client-side code, public repositories, or share them publicly. Use environment variables to store keys securely.

Example Authentication

Include your API key in the x-api-key header:

curl -X GET "https://api.mailchk.io/v1/check?email=test@example.com" \
  -H "x-api-key: YOUR_API_KEY"

Endpoints

GET /v1/check?email=test@example.com

Check a single email address for disposable domain detection, MX records, and risk scoring.

Response

{
  "email": "test@example.com",
  "domain": "example.com",
  "valid": true,
  "disposable": false,
  "scam_domain": false,
  "mx_exists": true,
  "mx_records": [
    { "exchange": "mx1.example.com", "priority": 10 }
  ],
  "blacklisted_mx": false,
  "free_email": false,
  "did_you_mean": "",
  "risk_score": "low",
  "risk_factors": [],
  "email_provider": "Google Workspace",
  "deliverability_score": 95,
  "spf": "pass",
  "dmarc": "pass",
  "normalized_email": "test@example.com",
  "is_aliased": false,
  "alias_type": null
}
POST /v1/check

Check a single email address using JSON body.

Request Body

{
  "email": "test@example.com"
}

Response

{
  "email": "test@example.com",
  "domain": "example.com",
  "valid": true,
  "disposable": false,
  "scam_domain": false,
  "mx_exists": true,
  "blacklisted_mx": false,
  "free_email": false,
  "did_you_mean": "",
  "risk_score": "low",
  "risk_factors": [],
  "email_provider": "Google Workspace",
  "deliverability_score": 95,
  "spf": "pass",
  "dmarc": "pass",
  "normalized_email": "test@example.com",
  "is_aliased": false,
  "alias_type": null
}
POST /v1/check/bulk

Check multiple email addresses in a single request (max 100).

Request Body

{
  "emails": [
    "test@example.com",
    "fake@tempmail.com"
  ]
}

Response

{
  "results": [
    {
      "email": "test@example.com",
      "domain": "example.com",
      "valid": true,
      "disposable": false,
      "scam_domain": false,
      "mx_exists": true,
      "blacklisted_mx": false,
      "free_email": false,
      "did_you_mean": "",
      "risk_score": "low",
      "risk_factors": [],
      "email_provider": "Google Workspace",
      "deliverability_score": 95,
      "spf": "pass",
      "dmarc": "pass",
      "normalized_email": "test@example.com",
      "is_aliased": false,
      "alias_type": null
    },
    {
      "email": "fake@tempmail.com",
      "domain": "tempmail.com",
      "valid": false,
      "disposable": true,
      "scam_domain": false,
      "mx_exists": false,
      "blacklisted_mx": false,
      "free_email": false,
      "did_you_mean": "",
      "risk_score": "critical",
      "risk_factors": ["disposable_domain", "no_mx_records"],
      "reason": "Disposable email domain detected",
      "email_provider": null,
      "deliverability_score": 0,
      "spf": "none",
      "dmarc": "none",
      "normalized_email": "fake@tempmail.com",
      "is_aliased": false,
      "alias_type": null
    }
  ]
}

Response Fields

FieldTypeDescription
emailstringThe normalized email address
domainstringThe domain portion of the email
validbooleanWhether the email format is valid
disposablebooleanWhether the domain is a known disposable email provider
scam_domainbooleanWhether the domain is flagged as scam, phishing, or malicious (470K+ domains, updated daily)
mx_existsbooleanWhether the domain has MX records (can receive email)
mx_recordsarray?List of MX records with exchange and priority (if available)
blacklisted_mxbooleanWhether any MX server IP is found on a DNS blacklist (DNSBL)
free_emailbooleanWhether the domain is a free email provider (Gmail, Yahoo, etc.)
did_you_meanstringSuggested correction if a common typo is detected
risk_scorestringRisk level: "low", "medium", "high", or "critical"
risk_factorsarrayList of detected risk factors (e.g., "disposable_domain")
reasonstring?Human-readable explanation when email has issues
normalized_emailstringThe canonical mailbox address with aliases stripped (dots, plus tags, provider aliases)
is_aliasedbooleanWhether the email uses aliasing (plus tags, dot tricks, domain aliases)
alias_typestring?Type of alias: "plus_addressing", "dot_variation", "provider_alias", or "subdomain_addressing"

Risk Factors

FactorWeightDescription
invalid_formatCriticalEmail format is invalid (instant fail)
disposable_domain+80Domain is a known disposable email provider
scam_domain+85Domain flagged as scam, phishing, or malicious (470K+ domains, updated daily)
no_mx_records+70Domain has no MX records (cannot receive email)
blacklisted_mx+40MX server IP is listed on a DNS blacklist (Spamcop, Barracuda, DroneBL)
possible_typo+60Domain appears to be a typo of a common provider
suspicious_pattern+25Local part has suspicious patterns (random chars)
role_account+15Role-based email (admin@, info@, support@)
free_provider+5Free email provider (Gmail, Yahoo, etc.)

Risk Score Levels

low

0-14 points. Safe to accept.

medium

15-39 points. Review recommended.

high

40-69 points. Consider rejecting.

critical

70+ points. Reject recommended.

Error Codes

400

Bad Request

Missing or invalid parameters

401

Unauthorized

Invalid or missing API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Something went wrong on our end

Webhooks

Pro & Business

Receive real-time HTTP POST notifications when email validations complete. Configure webhooks in your dashboard settings.

How It Works

1

Configure URL

Add your HTTPS endpoint in dashboard settings

2

Validate Emails

Use the API as normal to validate emails

3

Receive Events

We POST results to your endpoint in real-time

4

Verify Signature

Validate HMAC-SHA256 signatures for security

Event Types

EventDescriptionTrigger
validation.completedAn email validation has finishedAfter each API validation request

Payload Format

Each webhook delivery includes these headers and a JSON body:

Headers

Content-Typeapplication/json
X-Webhook-SignatureHMAC-SHA256 signature: v1=<hex-digest>
X-Webhook-TimestampUnix timestamp (seconds) when the event was sent
User-AgentMailchk-Webhooks/1.0

Body

{
  "event": "validation.completed",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "email": "user@example.com",
    "domain": "example.com",
    "valid": true,
    "disposable": false,
    "mx_exists": true,
    "blacklisted_mx": false,
    "free_email": false,
    "did_you_mean": "",
    "risk_score": "low",
    "risk_factors": [],
    "email_provider": "Google Workspace",
    "deliverability_score": 95,
    "spf": "pass",
    "dmarc": "pass"
  }
}

Verifying Signatures

Always verify webhook signatures to ensure requests are from Mailchk. The signature is computed as HMAC-SHA256(secret, timestamp + "." + body).

const crypto = require('crypto');

function verifyWebhook(payload, signature, timestamp, secret) {
  const message = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return signature === `v1=${expected}`;
}

// In your webhook handler:
app.post('/webhooks/mailchk', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const body = JSON.stringify(req.body);

  if (!verifyWebhook(body, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  console.log('Event:', req.body.event);
  console.log('Email:', req.body.data.email);
  res.status(200).send('OK');
});

Delivery & Retries

Your endpoint must respond with a 2xx status code within 10 seconds to acknowledge delivery.

Failed deliveries are retried up to 3 times with exponential backoff.

Webhook URLs must use HTTPS. HTTP endpoints are not supported.

You can view delivery history and send test events from your dashboard.

Up to 3 webhook endpoints can be configured per account.

Official SDKs & Plugins

Skip the boilerplate. Use our official libraries for your language.

Node.js

npm install @mailchk/sdk

Python

pip install mailchk

PHP

composer require mailchk/mailchk-php

WordPress

Download from plugin directory
View All SDKs & Plugins