Docs/API reference

Email Verification

Verify a list of email addresses in bulk, with no campaign and no sending, and download the results.

get /email-verification/jobs List email verification jobspost /email-verification/jobs Verify a list of email addresses (spends money)get /email-verification/jobs/{id} Get an email verification jobpost /email-verification/jobs/{id}/cancel Cancel an email verification jobget /email-verification/jobs/{id}/csv Download an email verification job as CSVget /email-verification/jobs/{id}/records List an email verification job's resultsget /email-verification/rates Get the email verification rate

List email verification jobs

get https://api.emailchaser.com/r/email-verification/jobs
Works with a read-only key

Returns the workspace's standalone verification jobs, newest first, with live counts and what each has billed.

Parameters

  • page integer in query

    Page number, from 1

    Default 1
  • size integer in query

    Page size, max 200

    Default 25
  • search string in query

    Filter by job name

Responses

Fields in the 200 response
  • count integer
    Example: 3
  • next boolean
    Example: false
  • results array of EmailVerificationJobResponse
    14 fields inside results
    • catchall integer

      Catchall accepts everything at the domain, so deliverability is likely but not proven.

      Example: 400
    • end_time string

      EndTime in RFC3339, zero while the job is still running.

      Example: 2026-09-10T09:14:00Z
    • error_code string

      ErrorCode is empty on a healthy job. monthly_limit_reached means the allowance ran out and the remaining addresses came back unknown rather than missing; they are still in the download, marked.

    • id string
      Example: 1234
    • invalid integer

      Invalid will bounce.

      Example: 280
    • meter_events integer

      MeterEvents is what the job has billed so far. Every check runs up to two providers and each one that answers is one event, so an address costs one event or two.

      Example: 3100
    • name string

      Name the job was created with.

      Example: Q3 conference list
    • processed integer

      Processed is how many have a verdict yet.

      Example: 1800
    • spent_usd number

      SpentUsd is MeterEvents priced at the meter rate: what this job adds to the invoice, not an estimate.

      Example: 5.27
    • start_time string

      StartTime in RFC3339.

      Example: 2026-09-10T09:00:00Z
    • state string

      State is pending, running, done, failed or canceled.

      Example: running
    • total integer

      Total addresses in the job.

      Example: 2500
    • unknown integer

      Unknown got no verdict, so it was NOT billed. Usually a provider failure or the workspace's monthly verification allowance running out mid-job, in which case error_code says which.

      Example: 20
    • valid integer

      Valid is deliverable.

      Example: 1100

Request

curl -X GET "https://api.emailchaser.com/r/email-verification/jobs" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 3,
  "next": false,
  "results": [
    {
      "catchall": 400,
      "end_time": "2026-09-10T09:14:00Z",
      "error_code": "",
      "id": "1234",
      "invalid": 280,
      "meter_events": 3100,
      "name": "Q3 conference list",
      "processed": 1800,
      "spent_usd": 5.27,
      "start_time": "2026-09-10T09:00:00Z",
      "state": "running",
      "total": 2500,
      "unknown": 20,
      "valid": 1100
    }
  ]
}

Verify a list of email addresses (spends money)

post https://api.emailchaser.com/r/email-verification/jobs
Needs a read and write key

SPENDS MONEY: every address checked adds metered usage to the workspace's next invoice. No campaign is created and nothing is sent. Each check runs up to two providers in a waterfall and every provider that returns a verdict is one billable verification credit, so an address costs ONE credit when the first provider rejects it outright and TWO otherwise. Call GET /email-verification/rates for the current per-credit price and use per_address_ceiling_usd to budget. An address that gets no verdict (a provider failure, a cancelled job, or the workspace's monthly verification allowance running out mid-job) is NOT billed and comes back with result unknown, still in the download. Duplicates are removed and unparseable entries are returned in invalid_emails before anything is charged. Requires an active or trialing subscription: a past_due workspace is refused with subscription_not_active, and a trialing workspace may submit up to 100 addresses in total across all its jobs, after which it is refused with trial_allowance_exceeded. Errors carry a machine-readable code: insufficient_allowance (402, with needed_usd and available_usd), trial_allowance_exceeded (402, with allowance and remaining), subscription_not_active (402), no_active_subscription (402) and invalid_request (400).

Request bodyJSON · CreateEmailVerificationJobRequest

  • emails array of string required

    Emails are the addresses to verify. Duplicates are removed before anything is charged, and syntactically invalid entries are returned in invalid_emails rather than billed.

    Example: ["ada@example.com","grace@example.com"]
  • name string required

    Name is what the job is called in the app. Required.

    Example: Q3 conference list

Responses

Fields in the 200 response
  • duplicate_rows integer

    DuplicateRows is how many repeats were removed. Each one would have been a second paid check for an answer already bought.

    Example: 12
  • estimate_high_usd number

    EstimateHighUsd assumes every address runs both providers. This is the common case and the number to plan against.

    Example: 8.5
  • estimate_low_usd number

    EstimateLowUsd assumes every address settles on the first provider.

    Example: 4.25
  • id string

    ID of the created job.

    Example: 1234
  • invalid_emails array of string

    InvalidEmails are the submitted entries that are not addresses at all. They were not charged for and are not in the job.

  • total integer

    Total is how many addresses were accepted, after removing duplicates and unparseable entries.

    Example: 2500

Request

curl -X POST "https://api.emailchaser.com/r/email-verification/jobs" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "ada@example.com",
    "grace@example.com"
  ],
  "name": "Q3 conference list"
}'

Response

{
  "duplicate_rows": 12,
  "estimate_high_usd": 8.5,
  "estimate_low_usd": 4.25,
  "id": "1234",
  "invalid_emails": [
    "string"
  ],
  "total": 2500
}

Get an email verification job

get https://api.emailchaser.com/r/email-verification/jobs/{id}
Works with a read-only key

Returns one job's progress and what it has billed so far. Poll this to know when state becomes done.

Parameters

  • id string required in path

    Job ID

Responses

Fields in the 200 response
  • catchall integer

    Catchall accepts everything at the domain, so deliverability is likely but not proven.

    Example: 400
  • end_time string

    EndTime in RFC3339, zero while the job is still running.

    Example: 2026-09-10T09:14:00Z
  • error_code string

    ErrorCode is empty on a healthy job. monthly_limit_reached means the allowance ran out and the remaining addresses came back unknown rather than missing; they are still in the download, marked.

  • id string
    Example: 1234
  • invalid integer

    Invalid will bounce.

    Example: 280
  • meter_events integer

    MeterEvents is what the job has billed so far. Every check runs up to two providers and each one that answers is one event, so an address costs one event or two.

    Example: 3100
  • name string

    Name the job was created with.

    Example: Q3 conference list
  • processed integer

    Processed is how many have a verdict yet.

    Example: 1800
  • spent_usd number

    SpentUsd is MeterEvents priced at the meter rate: what this job adds to the invoice, not an estimate.

    Example: 5.27
  • start_time string

    StartTime in RFC3339.

    Example: 2026-09-10T09:00:00Z
  • state string

    State is pending, running, done, failed or canceled.

    Example: running
  • total integer

    Total addresses in the job.

    Example: 2500
  • unknown integer

    Unknown got no verdict, so it was NOT billed. Usually a provider failure or the workspace's monthly verification allowance running out mid-job, in which case error_code says which.

    Example: 20
  • valid integer

    Valid is deliverable.

    Example: 1100

Request

curl -X GET "https://api.emailchaser.com/r/email-verification/jobs/abc123" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "catchall": 400,
  "end_time": "2026-09-10T09:14:00Z",
  "error_code": "",
  "id": "1234",
  "invalid": 280,
  "meter_events": 3100,
  "name": "Q3 conference list",
  "processed": 1800,
  "spent_usd": 5.27,
  "start_time": "2026-09-10T09:00:00Z",
  "state": "running",
  "total": 2500,
  "unknown": 20,
  "valid": 1100
}

Cancel an email verification job

post https://api.emailchaser.com/r/email-verification/jobs/{id}/cancel
Needs a read and write key

Stops a running job. Addresses already verified stay in the download and stay billed; addresses that never ran are never charged, so cancelling costs nothing further and needs no refund.

Parameters

  • id string required in path

    Job ID

Responses

Fields in the 200 response
  • message string
    Example: job canceled

Request

curl -X POST "https://api.emailchaser.com/r/email-verification/jobs/abc123/cancel" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "message": "job canceled"
}

Download an email verification job as CSV

get https://api.emailchaser.com/r/email-verification/jobs/{id}/csv
Works with a read-only key

Streams one row per submitted address. Every address is in the file, including the ones that came back unknown because the monthly allowance ran out: they are marked rather than dropped, so the file never has a silent hole in it.

Parameters

  • id string required in path

    Job ID

  • result string in query

    Filter by verdict

    One of: "valid", "catchall_validated", "invalid", "unknown", "deliverable"
  • columns string in query

    Comma-separated subset of columns, in order. Defaults to all: Email, Result, First check result, Second check result, Status, Verification Credits, Error, Verified At.

Responses

Request

curl -X GET "https://api.emailchaser.com/r/email-verification/jobs/abc123/csv" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

"string"

List an email verification job's results

get https://api.emailchaser.com/r/email-verification/jobs/{id}/records
Works with a read-only key

Returns one row per address with its verdict and what it billed. Filter with result: valid, catchall_validated, invalid, unknown, or deliverable (valid plus catch-all, which is what a campaign will send to).

Parameters

  • id string required in path

    Job ID

  • page integer in query

    Page number, from 1

    Default 1
  • size integer in query

    Page size, max 200

    Default 25
  • result string in query

    Filter by verdict

    One of: "valid", "catchall_validated", "invalid", "unknown", "deliverable"

Responses

Fields in the 200 response
  • count integer
    Example: 2500
  • next boolean
    Example: true
  • results array of EmailVerificationRecordResponse
    9 fields inside results
    • email string
      Example: ada@example.com
    • error string

      Error is set when the address could not be answered.

    • first_check_result string

      What the first check said.

      Example: valid
    • id string
      Example: 98765
    • meter_events integer

      MeterEvents is what this address billed: 0, 1 or 2.

      Example: 2
    • result string

      Result is valid, catchall_validated, invalid or unknown. The same four values a campaign's send-time gate uses, so an address checked here and one checked inside a campaign answer the same.

      Example: valid
    • second_check_result string

      What the second check said. unknown means it never ran, which is what happens when the first check rejected the address outright, and nothing was billed for it.

      Example: valid
    • status string

      Status is done, failed, skipped or pending.

      Example: done
    • verified_at string

      VerifiedAt in RFC3339.

      Example: 2026-09-10T09:02:11Z

Request

curl -X GET "https://api.emailchaser.com/r/email-verification/jobs/abc123/records" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "count": 2500,
  "next": true,
  "results": [
    {
      "email": "ada@example.com",
      "error": "",
      "first_check_result": "valid",
      "id": "98765",
      "meter_events": 2,
      "result": "valid",
      "second_check_result": "valid",
      "status": "done",
      "verified_at": "2026-09-10T09:02:11Z"
    }
  ]
}

Get the email verification rate

get https://api.emailchaser.com/r/email-verification/rates
Works with a read-only key

Returns the current price of a verification, read from the billing plans the meter actually charges against. Read this rather than assuming a rate: an address costs one credit when the first provider rejects it outright and two when both providers answer, so per_address_ceiling_usd is the figure to budget against.

Responses

Fields in the 200 response
  • first_check_usd number

    What one first check costs.

    Example: 0.0017
  • per_address_ceiling_usd number

    PerAddressCeilingUsd is the most an address can cost: both providers answering. This is the common case, so budget against this one.

    Example: 0.0034
  • per_address_floor_usd number

    PerAddressFloorUsd is the least an address can cost: the first provider alone, which happens when it rejects the address outright.

    Example: 0.0017
  • second_check_usd number

    What one second check costs.

    Example: 0.0017

Request

curl -X GET "https://api.emailchaser.com/r/email-verification/rates" \
  -H "Authorization: Bearer $EMAILCHASER_API_KEY"

Response

{
  "first_check_usd": 0.0017,
  "per_address_ceiling_usd": 0.0034,
  "per_address_floor_usd": 0.0017,
  "second_check_usd": 0.0017
}

Generated from the Emailchaser API's own OpenAPI definition, so it always matches the running API.