Reference · v1

ClearAddress API

The ClearAddress API provides a simple way to validate email addresses. One GET request per address, or up to 500 at once with POST. No key, no account, JSON back.

Email validation

GET https://ca.rda.run/v1/{email_address}?pretty

Validates one email address.

Parameters

Name	Required	Type	Description
`email_address`	yes	string	The specific email address to test.
`pretty`	no	flag	If present, the response will be formatted for human readability.

Responses

200application/json;charset=UTF-8

JSON string with the fields below.

400application/json

{"code":"400","message":"Bad Request"}

Response fields

Field	Type	Description
`email`	string	The email address being validated.
`localPart`	string	The local part of the email address.
`domain`	string	The domain part of the email address.
`hasValidDomain`	boolean	Indicates if the domain is valid.
`hasValidMX`	boolean	Indicates if the domain has valid MX records.
`hasValidSyntax`	boolean	Indicates if the email has valid syntax.
`isFunctional`	boolean	Indicates if the email is functional (a role mailbox such as info@ or support@).
`isDisposable`	boolean	Indicates if the email is disposable.
`isClear`	boolean	Indicates if we consider the email "clear": with an existing domain, with valid MX records, with valid syntax, not from a functional mailbox, and not from a disposable email service.

Example

Request · cURL

$ curl -fsSL "https://ca.rda.run/v1/user@example.org?pretty"

Response · 200

{
  "email": "user@example.org",
  "localPart": "user",
  "domain": "example.org",
  "hasValidDomain": true,
  "hasValidMX": true,
  "hasValidSyntax": true,
  "isFunctional": true,
  "isDisposable": false,
  "isClear": false
}

Bulk validation

POST https://ca.rda.run/v1/bulk?pretty

Send a JSON array of email addresses with Content-Type: application/json. The response has count and results: one item per address sent, in the same order (repeated and invalid ones included), each with exactly the fields above. Comparisons ignore case, but email, localPart and domain come back as sent. A DNS failure on one domain is not an error: its items return hasValidDomain and hasValidMX as false. pretty works as above. CORS is open, so browsers can call it directly. Prefer a form? Use the bulk page.

Limit per request	Value	Notes
Addresses	`500`	Larger lists must be split into several requests.
Distinct domains	`50`	Counted among addresses with valid syntax, ignoring case. DNS is queried once per domain, so 300 addresses on one domain count as 1.

400application/json

Body is not JSON, not an array, empty, or has items that are not text. {"error":"Body must be a non-empty JSON array of email addresses"}

413application/json

Over a limit. Nothing is processed; the body reports maxEmails, maxDomains, emails and domains.

Request · cURL

$ curl -fsSL -X POST "https://ca.rda.run/v1/bulk?pretty" -H "Content-Type: application/json" -d '["john.doe@rda.run","admin@rda.run","john@mailinator.com"]'

Response · 200

{
  "count": 3,
  "results": [
    {
      "email": "john.doe@rda.run",
      "localPart": "john.doe",
      "domain": "rda.run",
      "hasValidDomain": true,
      "hasValidMX": true,
      "hasValidSyntax": true,
      "isFunctional": false,
      "isDisposable": false,
      "isClear": true
    },
    ...
  ]
}