Contents

Documentación API

Llama a la API de verificación de correo con una clave API. Cada llamada exitosa descuenta 1 Credit del usuario de la clave.

Ejemplos de llamada

Envía la clave API en la petición (elige una):

curl -X GET "https://api.emailcheck.org/emailcheck/email/check?email=test%40gmail.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

Base URLhttps://api.emailcheck.org/emailcheckAll endpoints are served over HTTPS.

Response fields

Common business codes (HTTP still returns 200): C000301 unauthorized; C000501 too many trial requests; C000603 insufficient credit.

{
  "code": "S000000",
  "debugMessage": "success",
  "userMessage": "Operation successful! Congratulations!",
  "data": {
    "status": 200,
    "email": "test@gmail.com",
    "normalized_email": "test@gmail.com",
    "domain": "gmail.com",
    "domain_authority": 0,
    "domain_age_in_days": 11182,
    "mx": true,
    "mx_records": [
      { "hostname": "gmail-smtp-in.l.google.com", "priority": 5 }
    ],
    "mx_providers": [
      { "slug": "google", "type": "mailbox", "grade": "professional" }
    ],
    "disposable": false,
    "public_domain": true,
    "relay_domain": false,
    "alias": false,
    "role_account": false,
    "spam": false,
    "did_you_mean": null,
    "blocklisted": false
  },
  "requestId": "example-request-id"
}

Field	Description
`code`	Business result code. Observed success is S000000; common errors include C000301, C000501, and C000603.
`debugMessage`	Developer-facing debug text such as success, unauthorized, or too many requests.
`userMessage`	User-facing message string.
`requestId`	Request trace ID for log correlation.
`data.status`	Status code returned by the upstream verification provider; observed successful values are 200. This is not the outer HTTP status.
`email`	The email address that was checked.
`normalized_email`	Normalized email string; currently observed to usually match the input.
`domain`	Domain extracted from the email address.
`domain_authority`	Domain authority score; observed values can be 0.
`domain_age_in_days`	Domain age in days.
`mx`	Boolean enum: true \| false, whether MX records exist.
`mx_records[].hostname`	MX record hostname string.
`mx_records[].priority`	MX record priority integer.
`mx_providers[].slug`	Provider identifier such as google or yahoo.
`mx_providers[].type`	Provider type string; observed value is mailbox.
`mx_providers[].grade`	Provider grade string; observed values include professional and basic.
`disposable`	Boolean enum: true \| false, whether the domain is disposable.
`public_domain`	Boolean enum: true \| false, whether the domain is a public mailbox provider.
`relay_domain`	Boolean enum: true \| false, whether the domain is treated as a relay domain.
`alias`	Boolean enum: true \| false, whether the address is treated as an alias.
`role_account`	Boolean enum: true \| false, whether the address looks like a role account (for example admin@ or support@).
`spam`	Boolean enum: true \| false, whether the address is flagged as spam-risky.
`did_you_mean`	String or null; returns a suggested corrected email when a typo is detected, otherwise null.
`blocklisted`	Boolean enum: true \| false, whether the domain is on a blocklist.

alias, role_account and did_you_mean are evaluated against the full email address (not just the domain) and are best-effort — some responses may fall back to false / null. spam is evaluated at the domain level and is stable across calls.

Single address check

Performs an SMTP-level handshake to verify whether a mailbox can receive mail. Deducts 1 Credit per call. A synchronous request blocks up to ~20 seconds; if no terminal status is reached in time, the response returns status=TIMEOUT_PENDING and you use the jobId to poll the status endpoint below.

GET https://api.emailcheck.org/emailcheck/email/reachability?email=test%40example.com
Authorization: Bearer YOUR_API_KEY

// Response — 1 Credit is deducted regardless of status
{
  "code": "S000000",
  "data": {
    "jobId": "EVJ...",
    "email": "test@example.com",
    "status": "COMPLETE",            // PENDING | IN-PROGRESS | COMPLETE | FAILED | TIMEOUT_PENDING
    "emailAddressStatus": "VALID",   // VALID | INVALID | UNKNOWN | CATCH_ALL
    "completed": true
  }
}

Re-fetch the latest status using the jobId returned by the single check. The response shape is identical.

GET https://api.emailcheck.org/emailcheck/email/reachability/status/{jobId}
Authorization: Bearer YOUR_API_KEY

// Same response shape as the single-check endpoint.

Bulk submission

Up to 100 emails per request. 1 Credit is reserved per address accepted by the upstream provider. Locally-rejected entries (invalid format, duplicates in the same batch) are refunded immediately; per-job timeouts are refunded automatically once the batch finalises.

POST https://api.emailcheck.org/emailcheck/email/reachability/bulk
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "emails": ["alice@example.com", "bob@example.com"],
  "filename": "my-list.csv",         // optional, for display only
  "source": "api"                     // csv | manual | api (defaults to "manual")
}

// Response
{
  "code": "S000000",
  "data": {
    "bulkId": "EVB...",
    "status": "PROCESSING",           // PROCESSING | COMPLETE | TIMEOUT_PARTIAL
    "requestedCount": 2,
    "acceptedCount": 2,
    "rejectedCount": 0,
    "accepted": [
      { "jobId": "EVJ...", "email": "alice@example.com",
        "status": "PENDING", "emailAddressStatus": "UNKNOWN", "completed": false }
    ],
    "rejected": []                    // { email, status: "FAILED", errorCode, errorMessage }
  }
}

Manage a batch

Inspect batch progress, page through jobs inside a batch, export CSV, force-refresh non-final jobs, or list all batches for the current account. Results are delivered via provider callback or our background reconciler — polling is not required.

# All endpoints below require: Authorization: Bearer YOUR_API_KEY

# Batch summary: counts, status, timestamps
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}

# Paginate jobs inside a batch
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/items?offset=0&limit=100

# Export results as CSV
#   columns: email, status, email_address_status, completed_time, error
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/export.csv

# Force-refresh any job that hasn't reached a final status yet
POST https://api.emailcheck.org/emailcheck/email/reachability/bulk/{bulkId}/reconcile

# List all batches belonging to the current account
GET  https://api.emailcheck.org/emailcheck/email/reachability/bulk/list?offset=0&limit=20

Usage stats & recent logs

Per-account daily call counts (last 30 days) and the 20 most recent jobs, intended for dashboard/console views.

# Both endpoints require: Authorization: Bearer YOUR_API_KEY

# Daily call counts for the last 30 days
GET https://api.emailcheck.org/emailcheck/email/reachability/stats/daily

# 20 most recent jobs
GET https://api.emailcheck.org/emailcheck/email/reachability/logs/recent

Response fields

Field	Description
`jobId`	Local job ID (prefixed with "EVJ_"). Use with /email/reachability/status/{jobId} to re-fetch.
`email`	The email address that was submitted for verification.
`status`	Job lifecycle status: PENDING \| IN-PROGRESS \| COMPLETE \| FAILED \| TIMEOUT_PENDING. TIMEOUT_PENDING only appears on a single sync request that exceeded the poll window — the job is still running; call the status endpoint later.
`emailAddressStatus`	Mailbox verdict: VALID (deliverable) \| INVALID (not deliverable) \| UNKNOWN (could not determine, e.g. SMTP refused) \| CATCH_ALL (domain accepts all addresses). Only meaningful once status is final.
`completed`	True when status has reached a terminal state (COMPLETE or FAILED); you can stop polling.
`bulkId`	Bulk batch ID (prefixed with "EVB_").
`requestedCount`	Total emails submitted in this batch, including locally rejected ones.
`acceptedCount`	Emails that passed local validation and were forwarded to the provider.
`rejectedCount`	Emails rejected locally before reaching the provider (invalid format, duplicates within the batch, etc.).
`completedCount`	Number of jobs that have reached a COMPLETE status.
`timeoutCount`	Jobs marked FAILED for exceeding the reconciler TTL; their Credit is automatically refunded.
`deductCredit`	Credits actually charged for this batch (= acceptedCount before refunds).
`refundedCredit`	Cumulative Credits refunded (rejected + timeout).
`source`	Batch origin tag: csv \| manual \| api (defaults to manual). Used only for bookkeeping and UI.
`filename`	Optional filename for display purposes.
`createdTime`	Batch creation timestamp (Unix milliseconds).
`completedTime`	Timestamp when the batch reached a terminal state (Unix milliseconds); absent while still processing.
`errorCode`	Local rejection code: invalid_email \| duplicate_email, etc.
`errorMessage`	Human-readable explanation corresponding to errorCode.