Email Validation API

The API has a single endpoint with everything you need to validate an email address. The response includes many fields, but you mostly need the valid field. Some checks can be configured from your dashboard, and those settings directly affect the value of valid.

POST
https://api.realmail.dev/v1/validate
curl --location 'https://api.realmail.dev/v1/validate' --header 'x-api-key: YOUR_API_KEY' --header 'Content-Type: application/json' --data-raw '{
  "email": "email@domain.com"
}'
  
{
    "data": {
        "email": "email@domain.com",
        "valid_email_format": true,
        "suggestion": null,
        "suggested_email": null,
        "mx_found": true,
        "has_active_website": true,
        "is_disposable": false,
        "is_suspected_role": false,
        "free_email_provider": false,
        "reason_code": null,
        "reason_message": null,
        "valid": true,
        "remaining_validations": 15703
    }
}

Request

Headers

x-api-key
string
required
Your API key. Create and manage your keys in Settings › API keys in your dashboard.
Content-Type
string
required
Must be `application/json`.

Body

email
string
required
The email address to validate (up to 320 characters).

Response

Success

email
string
The email address you sent.
valid_email_format
boolean
Whether the address has a valid format according to RFC 5322.
suggestion
string
Suggested domain when a likely typo is detected (for example, `gmail.com` for `gmial.com`), or `null`.
suggested_email
string
The full email address with the suggested domain (for example, `john@gmail.com`), or `null`.
mx_found
boolean
Whether the domain has valid MX records, which it needs to receive email. It is `null` when it could not be checked (reason code `dns_unavailable`).
has_active_website
boolean
Whether the domain has an active website. For information only: it does not affect `valid`.
is_disposable
boolean
Whether the address belongs to a temporary or disposable email service, such as mailinator.com or 10minutemail.com.
is_suspected_role
boolean
Whether the address looks like a shared role address, such as admin@example.com or support@example.com.
free_email_provider
boolean
Whether the address belongs to a free email provider, such as Gmail or Outlook.
valid
boolean
Whether you should accept the address. When it is `false`, `reason_code` tells you why. Your rules in the dashboard (disposable, free, and role addresses) change this result. Domains on your block list are always invalid (reason code `blocklisted`). Domains on your allow list are always valid (reason code `allowlisted`) and skip every other check, so the check fields (`mx_found`, `has_active_website`, `is_disposable`, `is_suspected_role`, and `free_email_provider`) are `null`.
reason_code
string
Why the address was accepted or rejected: `invalid_email_format`, `blocklisted`, `allowlisted`, `invalid` (the domain does not accept email), `disposable_email`, `role_address`, `free_email`, or `dns_unavailable`. It is `null` for valid addresses. `dns_unavailable` means the domain's DNS did not respond in time, so we could not tell whether it accepts email: `valid` is `false`, you are not charged for the validation, and you can try again later.
reason_message
string
A human-readable explanation of `reason_code` that you can show to your users. You can customize these messages in your dashboard.
remaining_validations
number
Validation credits left in your account.

Error

name
string
Error type: `ValidationError` (400, invalid body), `ApiKeyError` (401, missing or invalid API key), `RateLimitError` (429, too many requests; see the `Retry-After` header), `QuotaExceededError` (429, no credits left), or `UnexpectedError` (500).
message
string
A description of the error.
code
number
The HTTP status code: 400, 401, 429, or 500.
RealMail - The email validation for SaaS | Product Hunt