Email API - FreeAPIService docs

Base path: /email

Validates an email address against the valid_email regex defined in common/Regex.js, then checks its domain against the disposable-domain table (fake_domains) and against the static reserved/undeliverable domain lists.

GET /email/check

Checks whether the supplied email address is syntactically valid and whether its domain is disposable, reserved or undeliverable.

Query parameters

Parameter	Required	Description
`email`	yes	The email address to validate.

Responses

Status	Body
`200`	`{ "email": "<email>", "ok": true\|false, "reason": { "valid_syntax": bool, "disposable": bool, "reserved": bool, "undeliverable": bool } }`
`400`	`{ "error": "email is mandatory" }`

ok is true only when valid_syntax is true and disposable, reserved and undeliverable are all false.

A syntactically invalid address is still a valid request, so it returns 200 with ok: false.

Domain checks

The domain and all its parent suffixes are tested, so sub-domains inherit the classification of their parent:

disposable: the exact domain exists in the fake_domains table.
reserved: the domain or any parent suffix is in the RFC 2606 / RFC 6761 reserved list (example, test, invalid, localhost, example.com, example.net, example.org, local, onion, home.arpa, ipv4only.arpa, resolver.arpa, service.arpa, eap.arpa).
undeliverable: the domain or any parent suffix is in the non-deliverable list (example.com, example.net, example.org, test, invalid).

Disposable domain data

The disposable check queries the fake_domains(domain TEXT) table. Refresh it with:

./scripts/update_domains.sh "$(pwd)/api.db"

The script downloads domains.txt and domains_strict.txt, merges them with sort -u, and replaces the table contents. It requires wget and the sqlite3 CLI. The committed api.db already holds ~104k domains; on a fresh database the table must be seeded or the request fails.

Examples

Valid address with sub-domain, + tag and dots:

curl "$BASE_URL/email/check?email=foo.bar+baz@sub.domain.co.uk"

{
    "email": "foo.bar+baz@sub.domain.co.uk",
    "ok": true,
    "reason": {
        "disposable": false,
        "reserved": false,
        "undeliverable": false,
        "valid_syntax": true
    }
}

Reserved domain (RFC 2606), including sub-domains:

curl "$BASE_URL/email/check?email=test@example.com"

{
    "email": "test@example.com",
    "ok": false,
    "reason": {
        "disposable": false,
        "reserved": true,
        "undeliverable": true,
        "valid_syntax": true
    }
}

curl "$BASE_URL/email/check?email=user@mail.example.com"

{
    "email": "user@mail.example.com",
    "ok": false,
    "reason": {
        "disposable": false,
        "reserved": true,
        "undeliverable": true,
        "valid_syntax": true
    }
}

Disposable domain:

curl "$BASE_URL/email/check?email=user@mailinator.com"

{
    "email": "user@mailinator.com",
    "ok": false,
    "reason": {
        "disposable": true,
        "reserved": false,
        "undeliverable": false,
        "valid_syntax": true
    }
}

Invalid address:

curl "$BASE_URL/email/check?email=bad@"

{
    "email": "bad@",
    "ok": false,
    "reason": {
        "disposable": false,
        "reserved": false,
        "undeliverable": false,
        "valid_syntax": false
    }
}

Missing parameter:

curl -i "$BASE_URL/email/check"

{
    "error": "email is mandatory"
}