---
title: "Verify one email address"
method: POST
path: "/verification/verify"
tags: ["Verification"]
---

# Verify one email address

`POST /verification/verify`

## Request

- Base URL: `https://warmysender.com/api/v1`
- URL: `https://warmysender.com/api/v1/verification/verify`
- Auth: HTTP bearer

Checks a single address and returns one of four outcomes with a plain-English reason. Note that a confirmed mailbox is only one of them — on a mail server that accepts every address the outcome is `risky`, which is deliverable-but-unconfirmable rather than bad. Answers we cannot confirm are always free.

Required scope: `verification:write`.

Accepts an optional `Idempotency-Key` header so a retry never spends a second credit.

Results are one of `valid`, `invalid`, `risky` or `unknown`. `risky` means the domain accepts every address, so delivery cannot be confirmed. `unknown` means no definitive answer — never charged.

## Request body

- object
  - `email` string, email, required: The address to check.

## Response `200`

Success

## Other responses

- `401`: `unauthorized` — Missing or invalid API key.
- `402`: `verifier_access_required` — Paying unblocks it: there is no plan on the account, or an invoice is unsettled, or the one free daily check is already used. Verification credits clear all three immediately and need no subscription — `details.reason` says which one it is.
- `403`: `verifier_access_required` — The plan on this account carries no monthly verification allowance (or the account is on hold). Credits still work without a plan — `details.can_buy_credits` says whether they can be bought.; `insufficient_scope` — The API key lacks the scope this endpoint requires.
- `429`: `verification_rate_limited` — More than 20 single checks in a minute for this workspace.; `allowance_exhausted` — The plan allowance is used up and there are no credits to cover the check. Nothing was charged.; `rate_limited` — Too many requests — slow down and retry after the Retry-After delay.
- `503`: `verifier_access_required` — We could not read this account's verification entitlement. This is NOT a refusal — retry shortly rather than treating the account as ineligible.; `verification_capacity_reserved` — Checking capacity is reserved for paid work right now. Nothing was used up — a free check is given back — so retry shortly.; `verification_unavailable` — Checking is temporarily unavailable. Nothing was charged.

---

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