Verify one email

Verify one email address.

curl --request POST \
  --url https://api.bounceless.io/v1/verify \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "email": "jsmith@example.com"
}
'

{
  "status": "completed",
  "presend": {
    "contract_version": 1,
    "status": "completed",
    "outcome": "actionable_verdict",
    "decision": "send",
    "verdict": "DELIVERABLE",
    "provider_family": "<string>",
    "confidence": 0.5,
    "reasons": [
      "<string>"
    ],
    "evidence_class": "<string>",
    "retry": {
      "eligible_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "affinity_required": true
    },
    "billing": {
      "disposition": "debited",
      "credits": 1
    },
    "history": {}
  },
  "requestId": "<string>",
  "decision": {},
  "engine": {
    "verifiedAt": "2023-11-07T05:31:56Z",
    "attempts": 1,
    "providerFamily": "<string>"
  },
  "engineJobId": "<string>"
}

{
  "status": "completed",
  "presend": {
    "contract_version": 1,
    "status": "completed",
    "outcome": "actionable_verdict",
    "decision": "send",
    "verdict": "DELIVERABLE",
    "provider_family": "<string>",
    "confidence": 0.5,
    "reasons": [
      "<string>"
    ],
    "evidence_class": "<string>",
    "retry": {
      "eligible_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "affinity_required": true
    },
    "billing": {
      "disposition": "debited",
      "credits": 1
    },
    "history": {}
  },
  "requestId": "<string>",
  "decision": {},
  "engine": {
    "verifiedAt": "2023-11-07T05:31:56Z",
    "attempts": 1,
    "providerFamily": "<string>"
  },
  "engineJobId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

POST

verify

Verify one email address.

curl --request POST \
  --url https://api.bounceless.io/v1/verify \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "email": "jsmith@example.com"
}
'

{
  "status": "completed",
  "presend": {
    "contract_version": 1,
    "status": "completed",
    "outcome": "actionable_verdict",
    "decision": "send",
    "verdict": "DELIVERABLE",
    "provider_family": "<string>",
    "confidence": 0.5,
    "reasons": [
      "<string>"
    ],
    "evidence_class": "<string>",
    "retry": {
      "eligible_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "affinity_required": true
    },
    "billing": {
      "disposition": "debited",
      "credits": 1
    },
    "history": {}
  },
  "requestId": "<string>",
  "decision": {},
  "engine": {
    "verifiedAt": "2023-11-07T05:31:56Z",
    "attempts": 1,
    "providerFamily": "<string>"
  },
  "engineJobId": "<string>"
}

{
  "status": "completed",
  "presend": {
    "contract_version": 1,
    "status": "completed",
    "outcome": "actionable_verdict",
    "decision": "send",
    "verdict": "DELIVERABLE",
    "provider_family": "<string>",
    "confidence": 0.5,
    "reasons": [
      "<string>"
    ],
    "evidence_class": "<string>",
    "retry": {
      "eligible_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "affinity_required": true
    },
    "billing": {
      "disposition": "debited",
      "credits": 1
    },
    "history": {}
  },
  "requestId": "<string>",
  "decision": {},
  "engine": {
    "verifiedAt": "2023-11-07T05:31:56Z",
    "attempts": 1,
    "providerFamily": "<string>"
  },
  "engineJobId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "requestId": "<string>"
  }
}

This page renders the machine-readable request, response, and status-code contract from openapi.yaml. Use it to inspect field shapes; use the single-verification guide for the operational workflow. The specification models canonical X-Api-Key authentication and HTTP Bearer compatibility for existing integrations; new code should use X-Api-Key. The source does not prefill a credential. Hosted-playground storage behavior requires a separate browser verification before launch, so use the curl quickstart with a controlled key until that check is complete. HTTP 200 includes the completed Pre-Send decision and engine metadata. HTTP 202 represents accepted or still-running work, carries no decision, and has no public single-result polling route in the four-route GA contract. Treat those response shapes separately in generated clients.

Authorizations

X-Api-Key

string

header

required

Canonical authentication. Send a Bounceless key in blc.… format.

Headers

Idempotency-Key

string

required

Minimum string length: 1

Body

application/json

string<email>

required

Maximum string length: 320

timeoutMs

integer

Required range: 1 <= x <= 120000

Response

Completed

status

enum<string>

required

Available options:

completed,

queued,

running

presend

object

required

Show child attributes

requestId

string

required

decision

object | null

engine

object

Present on a completed 200 response and absent while a 202 response is still accepted or running.

Show child attributes

engineJobId

string

Present on a 202 accepted response. No public single-result polling route is defined by this contract.

Start

Verify

Tools

API reference

Changes

Authorizations

Headers

Body

Response