---
title: "Verify Email"
method: POST
path: "/functions/v1/api/v2/verify-email"
---

# Verify Email

`POST /functions/v1/api/v2/verify-email`

## Request

- Base URL: `https://api.signaliz.com`
- URL: `https://api.signaliz.com/functions/v1/api/v2/verify-email`
- Auth: HTTP bearer

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `email` string, email, required
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `verification_run_id` string: Resume one long-running verification without starting another provider call
    - `requests` union[]: Up to 25 requests run synchronously. Larger batches use one recoverable verification job.
      - union
        - string, email
        - VerifyEmailBatchRequest
          - `email` string, email, required
          - `idempotency_key` string
    - `concurrency` integer
    - `job_id` string: Resume a recoverable Verify Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
    - `page` integer
    - `page_size` integer
  - object
    - `email` string, email
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `verification_run_id` string, required: Resume one long-running verification without starting another provider call
    - `requests` union[]: Up to 25 requests run synchronously. Larger batches use one recoverable verification job.
      - union
        - string, email
        - VerifyEmailBatchRequest
          - `email` string, email, required
          - `idempotency_key` string
    - `concurrency` integer
    - `job_id` string: Resume a recoverable Verify Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
    - `page` integer
    - `page_size` integer
  - object
    - `email` string, email
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `verification_run_id` string: Resume one long-running verification without starting another provider call
    - `requests` union[], required: Up to 25 requests run synchronously. Larger batches use one recoverable verification job.
      - union
        - string, email
        - VerifyEmailBatchRequest
          - `email` string, email, required
          - `idempotency_key` string
    - `concurrency` integer
    - `job_id` string: Resume a recoverable Verify Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
    - `page` integer
    - `page_size` integer
  - object
    - `email` string, email
    - `dry_run` boolean: Return a conservative credit estimate without provider calls, jobs, writes, or spend
    - `verification_run_id` string: Resume one long-running verification without starting another provider call
    - `requests` union[]: Up to 25 requests run synchronously. Larger batches use one recoverable verification job.
      - union
        - string, email
        - VerifyEmailBatchRequest
          - `email` string, email, required
          - `idempotency_key` string
    - `concurrency` integer
    - `job_id` string, required: Resume a recoverable Verify Email batch larger than 25 rows
    - `idempotency_key` string: Stable cross-surface retry key. Reuse it unless an error explicitly returns retry_strategy=new_idempotency_key together with credits_used=0 and credits_charged=0.
    - `batch_item_indices` integer[]: Stable global indexes for client-side chunks; one unique non-negative integer per request.
    - `page` integer
    - `page_size` integer

## Response `200`

Email verification result

- VerifyEmailResult
  - `index` integer
  - `dry_run` true
  - `input_count` integer
  - `fresh_input_count` integer
  - `unique_fresh_input_count` integer
  - `recovery_read_count` integer
  - `unique_recovery_read_count` integer
  - `plan` object
  - `estimate` object
  - `estimated_credits` object
  - `side_effects` unknown[]
    - unknown
  - `email` string, email
  - `status` 'valid' | 'invalid' | 'catch_all' | 'role' | 'disposable' | 'unknown' | 'verifier_error' | 'malformed'
  - `is_catch_all` boolean
  - `credits_charged` number
  - `verification_run_id` string
  - `run_id` string
  - `retry_after_ms` integer
  - `next_poll_after_seconds` integer
  - `suggested_action` string
  - `job_id` string
  - `job_capability` string
  - `idempotency_replayed` boolean
  - `idempotency_key` string
  - `page` integer
  - `page_size` integer
  - `total_results` integer
  - `total_pages` integer
  - `has_more` boolean
  - `total` integer
  - `succeeded` integer
  - `processing` integer
  - `failed` integer
  - `input_duplicates_suppressed` integer
  - `unique_tasks_dispatched` integer
  - `results` union[]
    - union
      - VerifyEmailResult (recursive)
      - CoreProductBatchError
        - `success` false, required
        - `error` string, required
        - `error_code` string, required: Stable machine code. PAYLOAD_TOO_LARGE means a durable Company Signal or Signal Copy request exceeded a per-field UTF-8 bound or the 8 MiB encoded request ceiling. BATCH_RESULTS_EXPIRED and RESULT_INTEGRITY_001 are nonretryable retained-result failures. PROVIDER_001 is a provider configuration or policy failure; PROVIDER_002 is provider noncompletion.
        - `message` string, required
        - `retry_eligible` boolean, required
        - `retry_after` integer
        - `retry_after_seconds` integer
        - `retry_strategy` 'new_idempotency_key' | 'same_run_recovery': new_idempotency_key permits an explicit fresh request only with zero-credit proof. same_run_recovery requires reading the returned run ID and forbids resubmitting the original request.
        - `credits_used` 0: Together with credits_charged=0, proves that this failed request consumed no Signaliz credits. Omission means unproven.
        - `credits_charged` 0: Together with credits_used=0, proves that this failed request consumed no Signaliz credits. Omission means unproven.
        - `run_id` string
        - `verification_run_id` string
        - `job_id` string
        - `idempotency_key` string
        - `suggested_action` string: Machine-readable recovery action. retry_with_run_id means resume existing provider work instead of dispatching a new run.
        - `do_not_auto_resubmit` boolean
        - `results_cleaned` boolean
        - `results_expired` boolean
        - `signal_run_id` string
        - `company_signal_run_id` string
        - `resume_context_persisted` boolean
        - `index` integer, required
        - `email` string, nullable, required
  - `ok_to_send` boolean
  - `verification_diagnostics` object: Page-scoped batch diagnostics. verified_count applies the same valid, ok_to_send, non-catch-all gate callers must use per row.
    - `scope` 'page'
    - `results_returned` integer
    - `verified_count` integer
    - `blocked_count` integer
    - `valid_but_blocked_count` integer
    - `verdict_counts` object
    - `send_safety_rule` string

## Other responses

- `202`: Verification is still running; retry with the returned verification_run_id or job_id
- `429`: Rate limited. Retry after the indicated delay.
- `502`: PROVIDER_001: email verification could not run under the configured provider policy. Obey retry_eligible; zero-credit fields are included only when proven.
- `504`: PROVIDER_002: an email provider did not complete. Retry only when retry_eligible is true; zero-credit fields are included only when proven.

---

[API](https://skmtc.dev/signaliz/apis/signaliz-api.md) · [All operations](https://skmtc.dev/signaliz/apis/signaliz-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaliz/apis/signaliz-api/revisions/53cb64feddad?raw)