pricklymails-com Verification API
Verify one address and read its result.
Verify one address and read its result.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/pricklymails-com:pricklymails-com-verification-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Pricklymails Com Verification API
version: 0.9.0
contact:
email: support@pricklymails.com
license:
name: Proprietary
description: 'Operations tagged verification across 2 of this provider''s published API definitions: pricklymails-com-openapi.json, pricklymails-com-openapi.yaml. Each path carries the servers of the definition it was published in.'
tags:
- name: Verification
description: Verify one address and read its result.
paths:
/api/verify:
post:
tags:
- Verification
summary: Submits a single-email verification job
description: 'Authenticated with a `pm_live_` or `pm_test_` API key, a dashboard session, or a scoped agent session token; the `email:verify:single` scope is required (a dashboard session always has it). A key-authed submit runs the checks enabled on the key and bills the key''s account. A `pm_test_` key takes the sandbox path: the response contract is the same, but no tokens are reserved and the result is a deterministic canned one chosen by the email''s local-part prefix, with no real probe. A session submit has no key: it always runs for real, bills the caller''s own account, and runs the default checks of the caller''s plan. An optional `checks` list runs those checks instead, each allowed on the caller''s plan (`403` otherwise), with their dependencies added (`smtp` brings `mx`, `catchall` brings both). Tokens are reserved when the job is accepted; a request that fails validation reserves nothing. Send an `Idempotency-Key` header to make retries safe: a replay of the same key and email returns `200` with an `Idempotent-Replayed: true` header instead of creating a second job. Send `Prefer: wait=N` to hold the response up to `N` seconds (at most 12) while the job runs: if it finishes in time, the response is `200` with the result in `verification`; otherwise it is the usual `202`, and the job keeps running. The job is processed the same way either way.'
operationId: submit_verification
parameters:
- name: Prefer
in: header
description: '`wait=N`: hold the response up to `N` seconds (at most 12) for the result. Answered with `Preference-Applied: wait=N`.'
required: false
schema:
type:
- string
- 'null'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitVerificationRequest'
required: true
responses:
'200':
description: 'Idempotent replay of a prior submission, or a job that finished within the `Prefer: wait` window, its result in `verification`.'
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitVerificationResponse'
'202':
description: Job accepted and queued.
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitVerificationResponse'
'400':
description: An unknown check name in `checks`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'402':
description: Wallet balance too low to reserve the job's cost.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: Caller is missing the `email:verify:single` scope, or a requested check is not allowed for the plan.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
/api/verify/{uuid}:
get:
tags:
- Verification
summary: Returns a verification job and its per-email results
description: Authenticated like `POST /api/verify` and limited to the caller's own jobs; a uuid that belongs to another account returns the same 404 as an unknown uuid. While the job has not reached a final status, the response carries a `Retry-After` header suggesting a poll delay.
operationId: get_verification
parameters:
- name: uuid
in: path
description: Public UUID of the verification job.
required: true
schema:
type: string
responses:
'200':
description: The job and its per-email verification results.
content:
application/json:
schema:
$ref: '#/components/schemas/GetVerificationResponse'
'400':
description: Malformed job `uuid`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'403':
description: Caller is missing the `results:read` scope.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'404':
description: No job with that uuid belongs to the caller.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
'429':
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorBody'
security:
- bearer_api_key: []
- jwt: []
components:
schemas:
ApiErrorBody:
type: object
description: 'Error envelope returned with every non-success status: `{ "error": { "code", "message" } }`.'
required:
- error
properties:
error:
$ref: '#/components/schemas/ApiErrorDetail'
description: Error detail.
MxCheckDto:
oneOf:
- type: object
description: The check ran.
required:
- valid
- records
properties:
records:
type: array
items:
type: string
description: MX record hostnames found for the domain.
valid:
type: boolean
description: 'Whether the domain publishes at least one usable mail exchanger.
`false` even when `records` is non-empty for an RFC 7505 null MX, exchangers that resolve to no address, or
a known parking placeholder; the `reason` names which.'
- type: object
description: The check was not run.
required:
- status
properties:
status:
type: string
description: Always `"skipped"`.
description: 'MX record check result.
Renders as `{ "status": "skipped" }` when the MX check did not run (excluded from the caller''s check set), the same
shape the `smtp` check uses for its own skipped state, so an unrun check never reads as a negative `valid: false`
result. When the check did run, it renders as `{ "valid": bool, "records": [...] }`.'
GetVerificationResponse:
type: object
description: '`GET /api/verify/{uuid}` response body.'
required:
- job_uuid
- status
- verifications
properties:
job_uuid:
type: string
description: Public UUID of the job.
status:
type: string
description: Current status of the job.
verifications:
type: array
items:
$ref: '#/components/schemas/VerificationResultDto'
description: 'Per-email verification rows.
Empty while the job is still pending or queued; populated once results are available.'
SmtpStatusDto:
type: string
description: Outcome of the SMTP probe.
enum:
- deliverable
- undeliverable
- unknown
- skipped
TypoCheckDto:
type: object
description: Typo detection result.
required:
- detected
properties:
detected:
type: boolean
description: Whether a domain typo was detected.
suggested_domain:
type:
- string
- 'null'
description: 'Corrected domain only (e.g. `"gmail.com"`), present on `GET /api/verify/{uuid}` when a typo was detected.
Only the domain is returned (zero-retention policy); the caller already has the local part to combine it with.'
suggestion:
type:
- string
- 'null'
description: 'Full corrected address (e.g. `"user@gmail.com"`), only ever present on the synchronous submit response where the
raw email is available in-request.
Always absent on `GET /api/verify/{uuid}`, because the submitted address is never stored (zero-retention
policy); `suggested_domain` is that path''s equivalent.'
CheckDurationsDto:
type: object
description: 'Per-check elapsed time in milliseconds.
Field names mirror the per-check result object one-to-one so a client can pair a check''s outcome with its timing.
`null` means the check did not run (disabled, or short-circuited by an earlier step), never that it took zero
milliseconds.'
properties:
catchall:
type:
- integer
- 'null'
format: int64
minimum: 0
disposable:
type:
- integer
- 'null'
format: int64
minimum: 0
free:
type:
- integer
- 'null'
format: int64
minimum: 0
mx:
type:
- integer
- 'null'
format: int64
minimum: 0
role:
type:
- integer
- 'null'
format: int64
minimum: 0
smtp:
type:
- integer
- 'null'
format: int64
minimum: 0
syntax:
type:
- integer
- 'null'
format: int64
minimum: 0
typo:
type:
- integer
- 'null'
format: int64
minimum: 0
SmtpCheckDto:
type: object
description: SMTP deliverability probe result.
required:
- status
properties:
status:
$ref: '#/components/schemas/SmtpStatusDto'
description: 'SMTP probe outcome: `deliverable` (the server accepted the `RCPT TO` command), `undeliverable` (the server
permanently rejected the recipient, 5xx), `unknown` (no definitive answer: a temporary refusal, a timeout, a
connection failure, or a server that refused the probe itself), or `skipped` (not requested, or not
needed because the answer was already known).'
ApiErrorDetail:
type: object
description: Detail of an error response.
required:
- code
properties:
code:
type: string
description: Stable key identifying the error (for example `"verify.invalid_uuid"`). Clients localize by this key.
message:
type:
- string
- 'null'
description: 'Present on most error kinds and equal to `code`; the API returns no localized text.
Absent for error kinds that carry no extra detail.'
SubmitVerificationRequest:
type: object
description: '`POST /api/verify` request body.'
required:
- email
properties:
checks:
type:
- array
- 'null'
items:
type: string
description: 'Optional explicit check names, each allowed on the caller''s plan; defaults to the key''s enabled checks, or to
the plan''s default checks for a dashboard session.'
email:
type: string
description: Email address to verify.
ProviderFlagDto:
oneOf:
- type: boolean
description: The check ran; carries the real boolean result.
- type: object
description: The check was not run.
required:
- status
properties:
status:
type: string
description: Always `"skipped"`.
description: 'A boolean provider or risk-flag check result (`disposable`, `role`, `free`, `catchall`).
Renders as a bare `true`/`false` when the check ran, or as `{ "status": "skipped" }` when it did not run (excluded
from the caller''s check set), the same skipped shape the `mx` and `smtp` checks use, so an unrun check never reads
as a definitive negative result.'
ChecksDto:
type: object
description: Individual check results for a verified email address.
required:
- syntax
- mx
- disposable
- role
- free
- typo
- smtp
- catchall
properties:
catchall:
$ref: '#/components/schemas/ProviderFlagDto'
description: Whether the domain is a catch-all server (accepts any address).
disposable:
$ref: '#/components/schemas/ProviderFlagDto'
description: Whether the domain is from a known disposable provider.
free:
$ref: '#/components/schemas/ProviderFlagDto'
description: 'Whether the domain is a known free webmail provider (gmail, yahoo, etc.). Free providers are informational and
do not change the quality score.'
mx:
$ref: '#/components/schemas/MxCheckDto'
description: MX record check result.
role:
$ref: '#/components/schemas/ProviderFlagDto'
description: 'Whether the local-part is a known role-based address (info@, support@, etc.). Role addresses are a risk factor
and reduce the quality score.'
smtp:
$ref: '#/components/schemas/SmtpCheckDto'
description: SMTP deliverability probe result.
syntax:
type: boolean
description: Whether the email syntax is valid.
typo:
$ref: '#/components/schemas/TypoCheckDto'
description: Typo detection result.
VerificationResultDto:
type: object
description: 'Per-email verification projection.
Email addresses are never stored (zero-retention policy); only keyed hashes are kept and returned here. The `checks`
object carries the per-step breakdown.
`checks.typo.suggestion` (the full corrected address) is always absent on this path;
`checks.typo.suggested_domain` (the corrected domain only) is present instead when a typo was detected.'
required:
- email_hash
- domain_hash
- status
- reason
- score
- recommendation
- verified_at
- checks
- durations
properties:
checks:
$ref: '#/components/schemas/ChecksDto'
description: Per-check breakdown of the verification result.
domain_hash:
type: string
description: Keyed hash of the email domain.
duration_ms:
type:
- integer
- 'null'
format: int64
minimum: 0
durations:
$ref: '#/components/schemas/CheckDurationsDto'
description: Per-check elapsed time in milliseconds.
email_hash:
type: string
description: Keyed hash of the normalized email address.
reason:
type: string
recommendation:
type: string
description: 'Deterministic list-cleaning action derived from `status`, `reason`, and the typo flag: one of `"remove"`,
`"send"`, or `"review"`. A presentation layer on top of the honest verdict above, not a replacement for it.'
score:
type: integer
format: int32
minimum: 0
status:
type: string
verified_at:
type: string
SubmitVerificationResponse:
type: object
description: '`POST /api/verify` response body.'
required:
- job_uuid
- status
- estimated_cost
- idempotency_key
- replayed
- email
properties:
email:
type: string
description: 'Echo of the submitted email address.
The address is never stored; this echo comes from the request itself so the caller can correlate the response to
its input.'
estimated_cost:
type: integer
format: int32
description: 'Total tokens reserved for the job.
Tokens for checks that did not complete are refunded when the job finishes.'
minimum: 0
idempotency_key:
type: string
description: 'Resolved idempotency key.
Either the client-supplied `Idempotency-Key` header or a generated UUID v4 when none was provided.'
job_uuid:
type: string
description: Public UUID of the persisted job. Use it with `GET /api/verify/{uuid}` to poll the result.
replayed:
type: boolean
description: '`true` when the response replays a prior submission made with the same idempotency key and the same email.'
status:
type: string
description: Current status of the job (`pending`, `queued`, `processing`, `completed`, `failed`, `canceled`).
suggestion:
type:
- string
- 'null'
description: 'Typo-corrected suggestion for the submitted email (e.g. `user@gmial.com` -> `user@gmail.com`), computed
synchronously at submit time.
Absent when no likely typo is detected.
Transient like `email`: never stored, so `GET /api/verify/{uuid}` never carries it.'
verification:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/VerificationResultDto'
description: 'The result, present when a `Prefer: wait` header held the response until the job finished.'
securitySchemes:
bearer_api_key:
type: http
scheme: bearer
description: A `pm_live_*` or `pm_test_*` API key.
jwt:
type: http
scheme: bearer
description: A short-lived token from `/api/auth/login`, or `/oauth/token` for an agent.
x-refined-from:
- pricklymails-com-openapi.json
- pricklymails-com-openapi.yaml