Email Validation

GET/v1/emails

Validates an email address and reports whether it is deliverable.

Requires an API Key licensed for email validation. A query over 320 characters is rejected.

A validated address decrements your lookup balance. An address the API cannot check returns unknown and costs no lookup. An address whose domain does not resolve, or publishes no MX records, returns not_deliverable and also costs no lookup. Only those two domain failures populate suggestions. Every other response returns an empty list.

Query parameters

api_key string optional: API Key

Your unique identifier that allows access to our APIs.

Begins ak_. Available from your dashboard.
Example ak_test
query string: Specifies the email address to validate
tags string optional: Tags

A comma separated list of tags to query over.

Useful if you want to specify the circumstances in which the request was made.

If you specify multiple tags, the response comprises only requests that satisfy all of them. Searching "foo,bar" queries only requests tagged both "foo" and "bar".
Example foo,bar

Response

result is a small, fixed object containing email validation attributes.

result one of
- Email
  - result string
    Values
    "deliverable"
    "not_deliverable"
  - deliverable boolean
    Returns true if the email can be delivered
  - disposable boolean
    Returns true if email comes from a disposable email service like temp-mail
  - free boolean
    Returns true if the email originates from a free service like Outlook or Gmail.
  - role boolean
    Returns true if email address represents an organisational role like admin, support, postmaster etc
  - catchall boolean
    Returns true if this domain accepts all emails regardless of username
  - suggestions string[]
    Returns an array of suggested email addresses if the email address is not deliverable. The suggested emails are not validated.
    Example
    corrected_email@example.com
- UnknownEmail
  - result string
    Values
    "unknown"
  - deliverable boolean
    Deliverability is not known
    Values
    "null"
  - disposable boolean
    Disposability is not known
    Values
    "null"
  - free boolean
    Free email provider is not known
    Values
    "null"
  - role boolean
    Role is not known
    Values
    "null"
  - catchall boolean
    Catch-all status is not known
    Values
    "null"
  - suggestions string[]
    Suggestions will be empty

The result sits inside the standard { result, code, message } envelope — see the API reference for the wrapper format.

Request

https://api.ideal-postcodes.co.uk/v1/emails?api_key=ak_test&query=foo@domain.com

curl -G 'https://api.ideal-postcodes.co.uk/v1/emails' \
  -d 'api_key=ak_test' \
  --data-urlencode 'query=foo@domain.com'

const response = await fetch(
  'https://api.ideal-postcodes.co.uk/v1/emails?' +
  new URLSearchParams({
    api_key: 'ak_test',
    query: 'foo@domain.com',
  })
);

const { result } = await response.json();

import requests

response = requests.get(
    "https://api.ideal-postcodes.co.uk/v1/emails",
    params={
        "api_key": "ak_test",
        "query": "foo@domain.com",
    },
)
result = response.json()["result"]

require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/emails")
uri.query = URI.encode_www_form(api_key: "ak_test", query: "foo@domain.com")
result = JSON.parse(Net::HTTP.get(uri))["result"]

<?php
$response = file_get_contents(
  "https://api.ideal-postcodes.co.uk/v1/emails?" .
  http_build_query([
    "api_key" => "ak_test",
    "query" => "foo@domain.com",
  ])
);
$result = json_decode($response, true)["result"];

Response

200 OK
400 Bad Request

{
  "result": {
    "result": "deliverable",
    "deliverable": true,
    "catchall": false,
    "free": false,
    "role": true,
    "disposable": false,
    "suggestions": []
  },
  "code": 2000,
  "message": "Success"
}

response.json
{
  "code": 4000,
  "message": "Invalid Request"
}

Query parameters​

Response​

Query parameters

Response