Skip to main content
POST
/
v1
/
verify
/
email
curl --request POST \
  --url https://api.waterfall.io/v1/verify/email \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "email": "jane.doe@acme.com"
}
'
{
  "status": "SUCCEEDED",
  "start_date": "2024-01-15T12:00:00.000000+00:00",
  "stop_date": "2024-01-15T12:00:01.000000+00:00",
  "input": {
    "task": {
      "email": "jane.doe@acme.com",
      "custom_fields": null,
      "job_id": "dae884ce-50aa-4208-b24f-f30687a00368",
      "context_id": "dae884ce-50aa-4208-b24f-f30687a00368"
    }
  },
  "output": {
    "email": {
      "email": "jane.doe@acme.com",
      "domain": "acme.com",
      "email_status": "valid",
      "smtp_provider": "Google",
      "mx_records": [
        "aspmx.l.google.com",
        "alt1.aspmx.l.google.com"
      ]
    }
  }
}
Email Verification OverviewYou input: Business or personal email addressYou get: Real-time deliverability status — valid, risky, invalid, or unknown
Unlike other Waterfall endpoints, this is synchronous — the result is returned immediately in the response. No job_id, no polling.

​
Status values

StatusMeaningWhat to do
validSafe to send. Mailbox confirmed.Send.
invalidHigh bounce risk. Mailbox does not exist or is disabled.Do not send.
riskyPotential bounce risk. Sending to risky addresses may cause bounces.Only send if your blended inbox-level bounce rate is already below 2%.
unknownDomain not responding — address looks valid but could not be confirmed. Not charged.Retry later; you won’t be billed for this result.

​
Business notes

Add your internal notes here — pricing, use cases, suppression logic, retry strategy for unknown, etc.
  • Billing: charged per verification call — unknown results are not billed
  • Catch-all domains: risky frequently indicates a catch-all domain, meaning the domain accepts all inbound mail without confirming individual mailboxes

Authorizations

​
x-api-key
string
header
required

To access the API, provide your API key in x-api-key.

Body

application/json

Verify Email payload. Requires a single email address and accepts optional custom_fields.

Request payload to verify a single email address.

​
email
string<email>
required

Professional or personal email address.

Maximum string length: 254
Example:

"john.doe@example.com"

​
custom_fields
object

Any custom key-value pairs echoed back in the Prospector Finder output (useful for correlating internal source metadata).

Example:
{
  "tenantId": "0e9d26b7-cdb5-4d95-b248-59ac389d2e8a",
  "workflowId": "ProspectFromWaterfall:23ed5bc8-a976-4ee0-b644-f0eb2db6e3ad:c268355e-a256-4593-a216-009a2463cee4",
  "waterfallRequestId": "1b49c542-f47a-406b-a95f-a1859d1461af"
}

Response

Email verification result returned immediately.

Verify Email response with status, input, and optional verified email output.

​
status
enum<string>
required

The status of the job.

Available options:
RUNNING,
SUCCEEDED,
FAILED,
TIMED_OUT,
ABORTED
Example:

"RUNNING"

​
start_date
string<date-time>
required

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771Z"

​
input
object
required
​
stop_date
string<date-time>

A date time in ISO 8601 format.

Example:

"2025-02-05T15:46:35.771Z"

​
output
object