API v1

AccessDeck API Documentation

Use AccessDeck API v1 to create email status check jobs, poll job progress, and fetch results for Gmail and Yahoo addresses. This document defines the public API contract. The current production implementation is an internal preview.

Base URL https://accessdeck.vip

Quick Start

Create a status check job with a Bearer API key.

curl -X POST https://accessdeck.vip/api/v1/email-check/jobs \
  -H "Authorization: Bearer adk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "auto",
    "mode": "auto",
    "emails": [
      "[email protected]",
      "[email protected]"
    ]
  }'

Authentication

Public API v1 should authenticate requests with an API key in the Authorization header.

Authorization: Bearer adk_live_xxx

The internal test endpoints currently use normal AccessDeck browser sessions. Do not use session-cookie endpoints as the final public integration contract.

Workflow

Create an email check job.
Poll the job until it is completed or failed.
Fetch JSON results or download CSV results.
Optionally receive a webhook when the job completes.

Supported providers auto, gmail, yahoo

Supported domains gmail.com, yahoo.com, ymail.com, rocketmail.com

Recommended mode auto

Endpoints

POST /api/v1/email-check/jobs GET /api/v1/email-check/jobs GET /api/v1/email-check/jobs/{job_id} GET /api/v1/email-check/jobs/{job_id}/results GET /api/v1/email-check/jobs/{job_id}/results.csv

POST

/api/v1/email-check/jobs

Create an email status check job.

Request

{
  "provider": "auto",
  "mode": "auto",
  "emails": [
    "[email protected]",
    "[email protected]"
  ],
  "webhookUrl": "https://client.example/webhooks/accessdeck"
}

Response

{
  "id": "job_123",
  "status": "queued",
  "provider": "auto",
  "mode": "auto",
  "totalItems": 2,
  "costCents": 2,
  "createdAt": "2026-07-11T09:26:03Z"
}

GET

/api/v1/email-check/jobs

List recent jobs for the authenticated account.

{
  "data": [
    {
      "id": "job_123",
      "status": "completed",
      "provider": "auto",
      "mode": "auto",
      "totalItems": 2,
      "checkedItems": 2,
      "liveCount": 1,
      "badCount": 1,
      "unknownCount": 0,
      "rateLimitedCount": 0,
      "costCents": 2
    }
  ],
  "hasMore": false
}

GET

/api/v1/email-check/jobs/{job_id}

Get one job and its aggregate counts.

{
  "id": "job_123",
  "status": "completed",
  "totalItems": 2,
  "checkedItems": 2,
  "liveCount": 1,
  "badCount": 1,
  "unknownCount": 0,
  "rateLimitedCount": 0,
  "error": null
}

GET

/api/v1/email-check/jobs/{job_id}/results

Fetch JSON result rows for a completed or running job.

{
  "data": [
    {
      "email": "[email protected]",
      "provider": "yahoo",
      "status": "live",
      "checkedAt": "2026-07-11T09:26:11Z"
    }
  ],
  "hasMore": false
}

GET

/api/v1/email-check/jobs/{job_id}/results.csv

Download results as CSV.

email,provider,status,checked_at
[email protected],yahoo,live,2026-07-11T09:26:11Z

Status Values

queuedAccepted and waiting to start.

runningThe checker is processing the job.

completedResults are available.

failedThe job failed. Check the error field.

liveThe address appears to exist or be active.

not_existThe address appears not to exist.

no_profileGmail People mode did not find a Google profile.

rate_limitedThe upstream provider rate limited the checker.

unknownThe response could not be confidently mapped.

Billing and Limits

Jobs are billed when they are created. Internal preview pricing is one cent per email.

costCents = emailCount * priceCents

Recommended public limits:

60 API requests per minute per API key
500 emails per job
10 active jobs per account

Error Format

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient balance.",
    "requestId": "req_abc123"
  }
}

Webhooks

Webhook support is planned for public API v1.

{
  "event": "email_check.completed",
  "jobId": "job_123",
  "status": "completed",
  "totalItems": 100,
  "checkedItems": 100,
  "liveCount": 91,
  "badCount": 6,
  "unknownCount": 3
}