Referencia de la API

Generada desde el contrato OpenAPI 3.1 de la API, que está escrito en inglés. Descárgalo como openapi.yaml u openapi.json, o lee esta referencia en Markdown. ¿Es tu primera vez? Empieza por el Inicio rápido.

La referencia interactiva necesita JavaScript. A continuación, el mismo contenido en HTML sencillo (en inglés).

Verify email addresses one at a time or in batches. SalchiMail never sends email: mailbox checks stop at RCPT TO and never issue DATA.

Authentication

Send your secret key on every request: Authorization: Bearer sk_live_…. Keys are created in the dashboard (https://app.salchimail.com), shown once and stored only as a hash. Keys are secrets: use them from servers, never from browsers or mobile apps.

sk_test_… keys run in test mode: no real verification is performed and no credits are used. Syntax is still checked; the verdict is chosen by the local part of the address: valid@… → valid, invalid@… → invalid, risky@… → risky (catch_all), disposable@… → risky (disposable_domain), anything else → unknown. Test batches complete within seconds. Test objects carry livemode: false.

Modes and credits

mode What it checks Credit used Can return valid
basic Syntax, domain lists (disposable, free), DNS/MX 1 basic credit No
mailbox Everything in basic + SMTP RCPT TO probe and catch-all control 1 mailbox credit Yes
  • basic never contacts the mail server, so a deliverable domain yields unknown (mailbox_not_checked) or risky (list signal), never valid.
  • basic: every completed verification costs 1 basic credit, except dns_temporary results and repeats of the same address within 30 days.
  • mailbox: 1 mailbox credit only when the verdict is not unknown. Repeats of the same address within 24 hours and duplicates inside a batch are free.
  • The two balances are independent: one never pays for the other.
  • credits_charged on every result tells you exactly what was charged.
  • With no credits left the API answers 402 insufficient_credits.

Verdicts

Verdict Meaning
valid The mail server accepts the recipient and rejects a random control address on the same server. It does not prove the mailbox is read.
invalid Unsupported syntax, a domain that cannot receive mail, or an unambiguous "no such recipient" rejection.
risky Accept-all server, disposable or legacy domain, forwarding, full or disabled mailbox, or a provider directory rejection without confirmation.
unknown Mailbox not checked (basic), timeout, greylisting, temporary DNS or SMTP failure, probe quota, ambiguous answer.

Do not treat unknown as invalid. A result with retry_at can be verified again after that time.

Rate limits

Limits depend on the plan and are reported by GET /account. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). Over the limit the API answers 429 with Retry-After.

Idempotency

POST operations accept an Idempotency-Key header (any unique string up to 255 characters, a UUID is recommended). Keys are kept 24 hours per account. A retry with the same key and the same body returns the stored response with Idempotent-Replayed: true and charges nothing. The same key with a different body returns 409 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_in_progress.

Errors

Every error uses one shape: {"error": {"type", "code", "message", "request_id"}}. type is the broad class, code is stable and machine-readable, message is for humans (localised with Accept-Language: en default, es). request_id equals the X-Request-Id response header; quote it to support.

HTTP type code
400 invalid_request invalid_json, missing_parameter, invalid_parameter, batch_empty, batch_too_large, csv_invalid, csv_column_not_found
401 authentication missing_api_key, invalid_api_key, revoked_api_key
402 payment_required insufficient_credits
403 permission mode_not_allowed, account_suspended
404 not_found not_found
409 conflict idempotency_key_reused, idempotency_in_progress, batch_not_cancelable
413 invalid_request payload_too_large
415 invalid_request unsupported_media_type
429 rate_limit rate_limit_exceeded, concurrent_batches_exceeded
500 api_error internal_error
503 api_error engine_unavailable, verification_timeout

New code and reason_code values may be added without a version bump: treat unknown values as their type or verdict.

Webhooks

Endpoints are configured in the dashboard. Each delivery is a POST with a JSON event and the header SalchiMail-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256(endpoint_secret, "<t>.<raw request body>"). Verify it with a constant-time comparison against the raw body and reject timestamps older than 5 minutes. During secret rotation several v1 values may be present: accept if any matches. Answer 2xx within 10 seconds; anything else is retried with exponential backoff for up to 24 hours (8 attempts). Deliveries can arrive more than once or out of order: deduplicate by event id.

Data retention

Batch inputs and results are deleted 30 days after the batch finishes. Single verifications are not stored in readable form.

Contents

Operations

Webhooks

Schemas

Servers

  • URL: https://api.salchimail.com/v1
    • Description: Production

Authentication

  • bearerAuth: HTTP bearer (API key)

    Secret API key: sk_live_… (live) or sk_test_… (test mode). Send it as Authorization: Bearer <key>.

Tags

Verification

Verify one address synchronously.

Batches

Verify lists asynchronously from JSON or CSV and download results.

Usage

Remaining credits and usage for the current period.

Account

The account, plan and limits behind the API key.

Webhooks

Signed events SalchiMail sends to your endpoints.

Operations

Verify one email address

  • Method: POST
  • Path: /verify
  • Operation ID: verifyEmail
  • Tags: Verification

Runs a verification and returns the result in the same response. basic normally answers in well under a second. mailbox talks to the recipient's mail server and can take up to 30 seconds; if it cannot finish in time the API answers 503 verification_timeout and charges nothing. For more than a few addresses use batches.

Servers: Inherited servers

Authentication: Global authentication

Header parameters
  • Idempotency-Key: string, minLength: 1, maxLength: 255

    Unique key that makes the request safe to retry for 24 hours.

    Example:

    JSON
    "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
  • Accept-Language: string, default: "en"

    Language of reason and error message. en (default) or es.

    Example:

    JSON
    "es"
Request body

Required: true

Content type: application/json

VerifyRequest

Example: basic

Without mailbox check (1 basic credit)

JSON
{
  "email": "ana@example.com"
}

Example: mailbox

With SMTP mailbox check (1 mailbox credit)

JSON
{
  "email": "ana@example.com",
  "mode": "mailbox"
}
Responses
200 Verification result.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42
  • Idempotent-Replayed

    Present and true when the response was replayed for a repeated Idempotency-Key.

    boolean

    Example:

    JSON
    true

Content type: application/json

Verification

Example: basicUnknown

basic mode, domain can receive mail

JSON
{
  "id": "ver_3f9a1c0b7d2e4a5f8b6c9d0e1f2a3b4c",
  "object": "verification",
  "livemode": true,
  "email": "ana@example.com",
  "mode": "basic",
  "verdict": "unknown",
  "reason_code": "mailbox_not_checked",
  "reason": "The domain can receive mail; the mailbox was not checked.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    }
  ],
  "mx": [
    {
      "host": "mx1.example.com",
      "preference": 10
    }
  ],
  "smtp": null,
  "cached": false,
  "credits_charged": 1,
  "checked_at": "2026-11-17T09:50:00Z",
  "retry_at": null
}

Example: mailboxValid

mailbox mode, recipient accepted and control rejected

JSON
{
  "id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
  "object": "verification",
  "livemode": true,
  "email": "ana@example.com",
  "mode": "mailbox",
  "verdict": "valid",
  "reason_code": "mailbox_exists",
  "reason": "The mail server accepts this recipient and rejects a random one.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": false
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    },
    {
      "name": "smtp",
      "status": "accepted"
    },
    {
      "name": "catch_all",
      "status": "missing"
    }
  ],
  "mx": [
    {
      "host": "mx1.example.com",
      "preference": 10
    }
  ],
  "smtp": {
    "mx": "mx1.example.com",
    "code": 250,
    "enhanced_code": null,
    "tls": true
  },
  "cached": false,
  "credits_charged": 1,
  "checked_at": "2026-11-17T09:50:04Z",
  "retry_at": null
}

Example: mailboxDeferred

mailbox mode, greylisted (not charged)

JSON
{
  "id": "ver_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "object": "verification",
  "livemode": true,
  "email": "luis@example.org",
  "mode": "mailbox",
  "verdict": "unknown",
  "reason_code": "smtp_temporary",
  "reason": "The mail server deferred the check; try again after retry_at.",
  "flags": {
    "disposable": false,
    "free": false,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": "ok"
    },
    {
      "name": "dns",
      "status": "mx"
    },
    {
      "name": "smtp",
      "status": "temporary"
    }
  ],
  "mx": [
    {
      "host": "mail.example.org",
      "preference": 5
    }
  ],
  "smtp": {
    "mx": "mail.example.org",
    "code": 451,
    "enhanced_code": "4.7.1",
    "tls": true
  },
  "cached": false,
  "credits_charged": 0,
  "checked_at": "2026-11-17T09:51:10Z",
  "retry_at": "2026-11-17T10:06:10Z"
}
400 The request is malformed or a parameter is invalid.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: missingParameter

Required field missing

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}

Example: batchTooLarge

Batch above the plan limit

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
402 Not enough credits of the type the request needs.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: insufficientCredits

No mailbox credits left

JSON
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "This request needs 3 mailbox credits and the account has 0.",
    "request_id": "req_4b5c6d7e8f9a0b1f"
  }
}
403 The key is valid but the account may not do this.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: modeNotAllowed

Mode not available to this account

JSON
{
  "error": {
    "type": "permission",
    "code": "mode_not_allowed",
    "message": "Mailbox verification is not enabled for this account.",
    "param": "mode",
    "request_id": "req_4b5c6d7e8f9a0b20"
  }
}
409 Idempotency conflict or the resource is in a state that does not allow the operation.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: keyReused

Same key, different body

JSON
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}

Example: notCancelable

Batch already finished

JSON
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
415 Use application/json or, for CSV batches, multipart/form-data.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: unsupported

Wrong Content-Type

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_media_type",
    "message": "Use Content-Type application/json.",
    "request_id": "req_4b5c6d7e8f9a0b25"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
503 The verification engine is unavailable or the check timed out. Nothing was charged.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12

Content type: application/json

ErrorResponse

Example: timeout

Mailbox check did not finish in time

JSON
{
  "error": {
    "type": "api_error",
    "code": "verification_timeout",
    "message": "The verification did not finish in time. Nothing was charged.",
    "request_id": "req_4b5c6d7e8f9a0b28"
  }
}

Create a batch from JSON or CSV

  • Method: POST
  • Path: /batches
  • Operation ID: createBatch
  • Tags: Batches

Queues a list for asynchronous verification and returns 202 at once.

  • JSON: up to 10,000 addresses in emails.
  • CSV: multipart/form-data with a UTF-8 file of up to 10 MB and 100,000 data rows. A header row is required and email_column must match one column name exactly. Only that column is stored; other columns are discarded. Join results back by row.

Your plan may set a lower limit (limits.max_batch_size in GET /account). Credits for every unique address are reserved when the batch is created (402 if the balance is too low) and unused credits are returned when it finishes. Duplicated addresses are verified once and charged once.

mailbox batches respect per-domain and per-server probe quotas and retry deferred addresses, so large lists concentrated on a few domains can take hours or days. Addresses still unresolved at deadline_at end as unknown and are not charged.

Servers: Inherited servers

Authentication: Global authentication

Header parameters
  • Idempotency-Key: string, minLength: 1, maxLength: 255

    Unique key that makes the request safe to retry for 24 hours.

    Example:

    JSON
    "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
Request body

Required: true

Content type: application/json

BatchCreateRequest

Example: json

JSON list with mailbox check

JSON
{
  "emails": [
    "ana@example.com",
    "luis@example.org",
    "not-an-email"
  ],
  "mode": "mailbox",
  "name": "November newsletter"
}

Content type: multipart/form-data

BatchCsvUpload

Example: csv

CSV upload (fields of the multipart form)

JSON
{
  "file": "id,email\n1,ana@example.com\n2,luis@example.org\n",
  "mode": "mailbox",
  "email_column": "email",
  "delimiter": "comma",
  "name": "November newsletter"
}

Encoding:

  • file
    • Content-Type: text/csv
Responses
202 Batch accepted and queued.

Headers:

  • Location

    URL of the new batch.

    string, format: uri

    Example:

    JSON
    "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42
  • Idempotent-Replayed

    Present and true when the response was replayed for a repeated Idempotency-Key.

    boolean

    Example:

    JSON
    true

Content type: application/json

Batch

Example: queued

Batch just created

JSON
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "queued",
  "total": 3,
  "unique": 3,
  "processed": 0,
  "summary": {
    "valid": 0,
    "invalid": 0,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 3,
    "charged": 0
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": null,
  "finished_at": null,
  "deadline_at": null,
  "results_expire_at": null
}
400 The request is malformed or a parameter is invalid.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: missingParameter

Required field missing

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}

Example: batchTooLarge

Batch above the plan limit

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
402 Not enough credits of the type the request needs.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: insufficientCredits

No mailbox credits left

JSON
{
  "error": {
    "type": "payment_required",
    "code": "insufficient_credits",
    "message": "This request needs 3 mailbox credits and the account has 0.",
    "request_id": "req_4b5c6d7e8f9a0b1f"
  }
}
403 The key is valid but the account may not do this.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: modeNotAllowed

Mode not available to this account

JSON
{
  "error": {
    "type": "permission",
    "code": "mode_not_allowed",
    "message": "Mailbox verification is not enabled for this account.",
    "param": "mode",
    "request_id": "req_4b5c6d7e8f9a0b20"
  }
}
409 Idempotency conflict or the resource is in a state that does not allow the operation.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: keyReused

Same key, different body

JSON
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}

Example: notCancelable

Batch already finished

JSON
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
413 The body exceeds 2 MB (JSON) or 10 MB (CSV).

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: tooLarge

CSV over 10 MB

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "payload_too_large",
    "message": "The file exceeds 10 MB. Split it into several batches.",
    "request_id": "req_4b5c6d7e8f9a0b24"
  }
}
415 Use application/json or, for CSV batches, multipart/form-data.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: unsupported

Wrong Content-Type

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "unsupported_media_type",
    "message": "Use Content-Type application/json.",
    "request_id": "req_4b5c6d7e8f9a0b25"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}
503 The verification engine is unavailable or the check timed out. Nothing was charged.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12

Content type: application/json

ErrorResponse

Example: timeout

Mailbox check did not finish in time

JSON
{
  "error": {
    "type": "api_error",
    "code": "verification_timeout",
    "message": "The verification did not finish in time. Nothing was charged.",
    "request_id": "req_4b5c6d7e8f9a0b28"
  }
}

List batches

  • Method: GET
  • Path: /batches
  • Operation ID: listBatches
  • Tags: Batches

Returns the account's batches, newest first.

Servers: Inherited servers

Authentication: Global authentication

Query parameters
  • limit: integer, default: 20, minimum: 1, maximum: 100

    Page size.

    Example:

    JSON
    20
  • cursor: string, maxLength: 255

    Opaque next_cursor from the previous page.

    Example:

    JSON
    "eyJyb3ciOjN9"
Responses
200 A page of batches.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

BatchList

Example: page

One completed batch

JSON
{
  "object": "list",
  "data": [
    {
      "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
      "object": "batch",
      "livemode": true,
      "name": "November newsletter",
      "source": "json",
      "mode": "mailbox",
      "status": "completed",
      "total": 3,
      "unique": 3,
      "processed": 3,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 0,
        "unknown": 1
      },
      "credits": {
        "type": "mailbox",
        "reserved": 0,
        "charged": 2
      },
      "created_at": "2026-11-17T09:50:00Z",
      "started_at": "2026-11-17T09:50:02Z",
      "finished_at": "2026-11-17T10:21:40Z",
      "deadline_at": "2026-11-23T09:50:02Z",
      "results_expire_at": "2026-12-17T10:21:40Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
400 The request is malformed or a parameter is invalid.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: missingParameter

Required field missing

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}

Example: batchTooLarge

Batch above the plan limit

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Get batch status

  • Method: GET
  • Path: /batches/{batch_id}
  • Operation ID: getBatch
  • Tags: Batches

Poll this endpoint (every few seconds at most) or subscribe to the batch.completed webhook. processed grows as addresses reach a final result.

Servers: Inherited servers

Authentication: Global authentication

Path parameters
  • batch_id (required): string, pattern: ^bat_[a-f0-9]{32}$

    Batch identifier.

    Example:

    JSON
    "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
Responses
200 The batch.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

Batch

Example: processing

Batch in progress

JSON
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "processing",
  "total": 3,
  "unique": 3,
  "processed": 2,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 1,
    "charged": 2
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": "2026-11-17T09:50:02Z",
  "finished_at": null,
  "deadline_at": "2026-11-23T09:50:02Z",
  "results_expire_at": null
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
404 The resource does not exist, belongs to another account or has expired.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: notFound

Unknown batch

JSON
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Get batch results (JSON or CSV)

  • Method: GET
  • Path: /batches/{batch_id}/results
  • Operation ID: listBatchResults
  • Tags: Batches

Returns results ordered by row. Only rows with a final result are listed, so pages requested while the batch is processing are partial: wait for a terminal status for a complete export. Rows never processed in a canceled batch are omitted.

With format=csv the body is CSV with the header row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at and the next page is given by the Link header (rel="next"). Results are deleted at results_expire_at; after that this endpoint answers 404.

Servers: Inherited servers

Authentication: Global authentication

Path parameters
  • batch_id (required): string, pattern: ^bat_[a-f0-9]{32}$

    Batch identifier.

    Example:

    JSON
    "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
Query parameters
  • format: string, possible values: "json", "csv", default: "json"

    Response format.

    Example:

    JSON
    "json"
  • verdict: string, possible values: "valid", "invalid", "risky", "unknown"

    Only return rows with this verdict.

    Example:

    JSON
    "valid"
  • limit: integer, default: 100, minimum: 1, maximum: 10000

    Page size. Maximum 1,000 for JSON and 10,000 for CSV.

    Example:

    JSON
    100
  • cursor: string, maxLength: 255

    Opaque next_cursor from the previous page.

    Example:

    JSON
    "eyJyb3ciOjN9"
Header parameters
  • Accept-Language: string, default: "en"

    Language of reason and error message. en (default) or es.

    Example:

    JSON
    "es"
Responses
200 A page of results.

Headers:

  • Link

    Next page as <url>; rel="next". Absent on the last page.

    string

    Example:

    JSON
    "<https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?format=csv&cursor=eyJyb3ciOjN9>; rel=\"next\""
  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

BatchResultList

Example: page

Two rows, more available

JSON
{
  "object": "list",
  "data": [
    {
      "row": 1,
      "input": "Ana@Example.com",
      "duplicate": false,
      "id": "ver_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f",
      "object": "verification",
      "livemode": true,
      "email": "ana@example.com",
      "mode": "mailbox",
      "verdict": "valid",
      "reason_code": "mailbox_exists",
      "reason": "The mail server accepts this recipient and rejects a random one.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": false
      },
      "checks": [
        {
          "name": "syntax",
          "status": "ok"
        },
        {
          "name": "dns",
          "status": "mx"
        },
        {
          "name": "smtp",
          "status": "accepted"
        },
        {
          "name": "catch_all",
          "status": "missing"
        }
      ],
      "mx": [
        {
          "host": "mx1.example.com",
          "preference": 10
        }
      ],
      "smtp": {
        "mx": "mx1.example.com",
        "code": 250,
        "enhanced_code": null,
        "tls": true
      },
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:04Z",
      "retry_at": null
    },
    {
      "row": 3,
      "input": "not-an-email",
      "duplicate": false,
      "id": "ver_1b2c3d4e5f60718293a4b5c6d7e8f9a0",
      "object": "verification",
      "livemode": true,
      "email": "not-an-email",
      "mode": "mailbox",
      "verdict": "invalid",
      "reason_code": "syntax_invalid",
      "reason": "The address is not a valid email.",
      "flags": {
        "disposable": false,
        "free": false,
        "catch_all": null
      },
      "checks": [
        {
          "name": "syntax",
          "status": "invalid"
        }
      ],
      "mx": [],
      "smtp": null,
      "cached": false,
      "credits_charged": 1,
      "checked_at": "2026-11-17T09:50:02Z",
      "retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "eyJyb3ciOjN9"
}

Content type: text/csv

string

Example: page

Same page as CSV

JSON
"row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at\n1,Ana@Example.com,ana@example.com,valid,mailbox_exists,false,false,false,1,2026-11-17T09:50:04Z\n3,not-an-email,not-an-email,invalid,syntax_invalid,false,false,,1,2026-11-17T09:50:02Z\n"
400 The request is malformed or a parameter is invalid.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: missingParameter

Required field missing

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The email field is required.",
    "param": "email",
    "request_id": "req_4b5c6d7e8f9a0b1c"
  }
}

Example: batchTooLarge

Batch above the plan limit

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "batch_too_large",
    "message": "This plan accepts up to 100 addresses per batch.",
    "param": "emails",
    "request_id": "req_4b5c6d7e8f9a0b1d"
  }
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
404 The resource does not exist, belongs to another account or has expired.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: notFound

Unknown batch

JSON
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Cancel a batch

  • Method: POST
  • Path: /batches/{batch_id}/cancel
  • Operation ID: cancelBatch
  • Tags: Batches

Stops a queued or processing batch. Results already produced stay available and charged; credits reserved for the rest are returned. Canceling a batch that is already canceled returns it unchanged; a completed or failed batch answers 409 batch_not_cancelable.

Servers: Inherited servers

Authentication: Global authentication

Path parameters
  • batch_id (required): string, pattern: ^bat_[a-f0-9]{32}$

    Batch identifier.

    Example:

    JSON
    "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
Header parameters
  • Idempotency-Key: string, minLength: 1, maxLength: 255

    Unique key that makes the request safe to retry for 24 hours.

    Example:

    JSON
    "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
Responses
200 The canceled batch.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42
  • Idempotent-Replayed

    Present and true when the response was replayed for a repeated Idempotency-Key.

    boolean

    Example:

    JSON
    true

Content type: application/json

Batch

Example: canceled

Canceled after two results

JSON
{
  "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "object": "batch",
  "livemode": true,
  "name": "November newsletter",
  "source": "json",
  "mode": "mailbox",
  "status": "canceled",
  "total": 3,
  "unique": 3,
  "processed": 2,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 0,
    "unknown": 0
  },
  "credits": {
    "type": "mailbox",
    "reserved": 0,
    "charged": 2
  },
  "created_at": "2026-11-17T09:50:00Z",
  "started_at": "2026-11-17T09:50:02Z",
  "finished_at": "2026-11-17T09:55:00Z",
  "deadline_at": "2026-11-23T09:50:02Z",
  "results_expire_at": "2026-12-17T09:55:00Z"
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
404 The resource does not exist, belongs to another account or has expired.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: notFound

Unknown batch

JSON
{
  "error": {
    "type": "not_found",
    "code": "not_found",
    "message": "Batch not found.",
    "request_id": "req_4b5c6d7e8f9a0b21"
  }
}
409 Idempotency conflict or the resource is in a state that does not allow the operation.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: keyReused

Same key, different body

JSON
{
  "error": {
    "type": "conflict",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "req_4b5c6d7e8f9a0b22"
  }
}

Example: notCancelable

Batch already finished

JSON
{
  "error": {
    "type": "conflict",
    "code": "batch_not_cancelable",
    "message": "A completed batch cannot be canceled.",
    "request_id": "req_4b5c6d7e8f9a0b23"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Get remaining credits and current usage

  • Method: GET
  • Path: /usage
  • Operation ID: getUsage
  • Tags: Usage

remaining is what you can spend now; credits held by running batches are reported separately in reserved. Basic credits are a monthly allowance that resets at resets_at and does not roll over. Mailbox credits come from one-off packs; credits closest to expiring are spent first.

Servers: Inherited servers

Authentication: Global authentication

Responses
200 Credits and usage.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

Usage

Example: usage

Basic plan with a mailbox pack

JSON
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 18760,
      "reserved": 0,
      "granted": 20000,
      "resets_at": "2026-12-01T00:00:00Z"
    },
    "mailbox": {
      "remaining": 2311,
      "reserved": 1,
      "next_expiry": null
    }
  },
  "period": {
    "start": "2026-11-01T00:00:00Z",
    "end": "2026-12-01T00:00:00Z"
  },
  "usage": {
    "basic": {
      "verifications": 1302,
      "credits_charged": 1240
    },
    "mailbox": {
      "verifications": 214,
      "credits_charged": 188
    }
  }
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Get the account behind the API key

  • Method: GET
  • Path: /account
  • Operation ID: getAccount
  • Tags: Account

Returns the organisation, its plan, the key in use and the limits that apply to it.

Servers: Inherited servers

Authentication: Global authentication

Responses
200 The account.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

Account

Example: account

Organisation on the Basic plan

JSON
{
  "id": "org_7a8b9c0d1e2f3a4b",
  "object": "account",
  "livemode": true,
  "name": "Acme Marketing",
  "plan": {
    "id": "basic",
    "status": "active"
  },
  "api_key": {
    "id": "key_2f3a4b5c6d7e8f9a",
    "name": "Production server",
    "prefix": "sk_live_a1b2",
    "created_at": "2026-11-02T08:15:00Z"
  },
  "limits": {
    "requests_per_minute": 600,
    "max_batch_size": 100000,
    "max_concurrent_batches": 3,
    "modes": [
      "basic",
      "mailbox"
    ]
  },
  "created_at": "2026-11-02T08:10:00Z"
}
401 The API key is missing, invalid or revoked.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • WWW-Authenticate

    Always Bearer.

    string

    Example:

    JSON
    "Bearer"

Content type: application/json

ErrorResponse

Example: invalidKey

Unknown key

JSON
{
  "error": {
    "type": "authentication",
    "code": "invalid_api_key",
    "message": "The API key is not valid.",
    "request_id": "req_4b5c6d7e8f9a0b1e"
  }
}
429 Rate limit or concurrent batch limit exceeded.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"
  • Retry-After

    Seconds to wait before retrying.

    integer

    Example:

    JSON
    12
  • RateLimit-Limit

    Requests allowed in the current window.

    integer

    Example:

    JSON
    600
  • RateLimit-Remaining

    Requests left in the current window.

    integer

    Example:

    JSON
    598
  • RateLimit-Reset

    Seconds until the current window resets.

    integer

    Example:

    JSON
    42

Content type: application/json

ErrorResponse

Example: rateLimited

Too many requests

JSON
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry in 12 seconds.",
    "request_id": "req_4b5c6d7e8f9a0b26"
  }
}
500 Unexpected error on our side. Safe to retry with the same Idempotency-Key.

Headers:

  • X-Request-Id

    Identifier of this request; the same value as error.request_id.

    string

    Example:

    JSON
    "req_4b5c6d7e8f9a0b1c"

Content type: application/json

ErrorResponse

Example: internal

Internal error

JSON
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side.",
    "request_id": "req_4b5c6d7e8f9a0b27"
  }
}

Webhooks

A batch finished

  • Method: POST
  • Webhook: batch.completed
  • Operation ID: onBatchCompleted
  • Tags: Webhooks

Sent when a batch reaches completed or failed (check data.batch.status). Not sent for batches you cancel. Fetch the rows with GET /batches/{batch_id}/results.

Servers: Inherited servers

Authentication

No authentication required.

Header parameters
  • SalchiMail-Signature (required): string

    t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the endpoint secret>.

    Example:

    JSON
    "t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
Request body

Required: true

Content type: application/json

BatchCompletedEvent

Example: completed

Batch completed

JSON
{
  "id": "evt_9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f",
  "object": "event",
  "type": "batch.completed",
  "livemode": true,
  "created_at": "2026-11-17T10:21:41Z",
  "data": {
    "batch": {
      "id": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
      "object": "batch",
      "livemode": true,
      "name": "November newsletter",
      "source": "json",
      "mode": "mailbox",
      "status": "completed",
      "total": 3,
      "unique": 3,
      "processed": 3,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 0,
        "unknown": 1
      },
      "credits": {
        "type": "mailbox",
        "reserved": 0,
        "charged": 2
      },
      "created_at": "2026-11-17T09:50:00Z",
      "started_at": "2026-11-17T09:50:02Z",
      "finished_at": "2026-11-17T10:21:40Z",
      "deadline_at": "2026-11-23T09:50:02Z",
      "results_expire_at": "2026-12-17T10:21:40Z"
    }
  }
}
Responses
200 Acknowledged. Any 2xx within 10 seconds stops retries.
4XX Any non-2xx answer or a timeout schedules a retry.

A credit balance fell below its threshold

  • Method: POST
  • Webhook: credits.low
  • Operation ID: onCreditsLow
  • Tags: Webhooks

Sent once each time a balance crosses the threshold configured in the dashboard (default: 10% of the last grant). It is sent again only after the balance has been topped up above the threshold and falls below it again.

Servers: Inherited servers

Authentication

No authentication required.

Header parameters
  • SalchiMail-Signature (required): string

    t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the endpoint secret>.

    Example:

    JSON
    "t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
Request body

Required: true

Content type: application/json

CreditsLowEvent

Example: low

Mailbox credits running low

JSON
{
  "id": "evt_0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
  "object": "event",
  "type": "credits.low",
  "livemode": true,
  "created_at": "2026-11-17T11:02:13Z",
  "data": {
    "credit_type": "mailbox",
    "remaining": 249,
    "threshold": 250
  }
}
Responses
200 Acknowledged. Any 2xx within 10 seconds stops retries.
4XX Any non-2xx answer or a timeout schedules a retry.

Schemas

Mode

Type: string, possible values: "basic", "mailbox"

basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

Verdict

Type: string, possible values: "valid", "invalid", "risky", "unknown"

ReasonCode

Type: string

Stable reason for the verdict. New values may be added.

Code Verdict Mode Meaning
syntax_invalid invalid both Not a valid address in the supported ASCII profile.
address_unsupported unknown both Internationalised (non-ASCII) address; not checked.
domain_not_found invalid both The domain does not exist (NXDOMAIN).
domain_null_mx invalid both The domain declares it accepts no mail (null MX, RFC 7505).
domain_no_mail_host invalid both No MX and no A/AAAA record.
dns_temporary unknown both DNS failed temporarily. Not charged.
mailbox_not_checked unknown basic Domain can receive mail; mailbox not probed.
disposable_domain risky both Domain is on the disposable list.
legacy_domain risky both Domain of a discontinued provider.
mailbox_exists valid mailbox Recipient accepted, random control rejected.
mailbox_not_found invalid mailbox Server says the recipient does not exist.
mailbox_disabled risky mailbox Server says the mailbox is disabled.
mailbox_full risky mailbox Server says the mailbox is full.
mailbox_forwarded risky mailbox Server announces forwarding (251).
provider_directory_rejected risky mailbox Provider directory rejection (Microsoft 365) without confirmation.
catch_all risky mailbox Server also accepts a random recipient.
catch_all_unresolved unknown mailbox Recipient accepted but the catch-all control was inconclusive.
rejection_unconfirmed unknown mailbox Rejected, but a known-good control was rejected too.
probe_rate_limited unknown mailbox Our hourly probe quota for that domain or server is exhausted.
probe_blocked unknown mailbox The server refuses our probe (IP reputation, reverse DNS or sender policy).
smtp_temporary unknown mailbox Temporary rejection or greylisting.
smtp_unreachable unknown mailbox No mail server could be reached.
smtp_tls_failed unknown mailbox The advertised TLS session could not be verified.
smtp_rejected unknown mailbox Ambiguous or policy rejection that does not prove the mailbox is missing.

Example:

JSON
"mailbox_exists"

Check

Type: object

One step that was actually executed, in order. Steps that did not run are absent (for example smtp in basic mode, or dns after a syntax failure).

name status values
syntax ok, invalid, unsupported
disposable, legacy, free matched (listed only when the domain matches)
dns mx, implicit_mx, nxdomain, null_mx, no_mail_host, temporary
smtp accepted, missing, provider_missing, disabled, full, forwarded, temporary, limited, unreachable, tls_failed, rejected
catch_all same values as smtp, for the random control recipient
  • name (required): string, possible values: "syntax", "disposable", "legacy", "free", "dns", "smtp", "catch_all"

  • status (required): string

    Outcome of the step. New values may be added.

Generated example:

JSON
{
  "name": "syntax",
  "status": ""
}

Flags

Type: object

  • catch_all (required): boolean | null

    true: the server also accepted a random recipient. false: it rejected the random recipient. null: not tested (basic mode, recipient not accepted) or inconclusive.

  • disposable (required): boolean

    The domain (or a parent domain) is on the disposable-email list.

  • free (required): boolean

    The domain is a free webmail provider. Informational; does not change the verdict.

Generated example:

JSON
{
  "disposable": true,
  "free": true,
  "catch_all": null
}

MxRecord

Type: object

  • host (required): string
  • preference (required): integer, minimum: 0, maximum: 65535

Generated example:

JSON
{
  "host": "",
  "preference": 0
}

SmtpEvidence

Type: object

What the recipient's server answered to RCPT TO for this address.

  • code (required): integer | null

    SMTP reply code, when a reply was received.

  • enhanced_code (required): string | null

    Enhanced status code (RFC 3463), when present.

  • mx (required): string | null

    Mail server that answered.

  • tls (required): boolean

    Whether the session used verified TLS.

Generated example:

JSON
{
  "mx": null,
  "code": null,
  "enhanced_code": null,
  "tls": true
}

Verification

Type: object

  • cached (required): boolean

    The result was served from a recent check; checked_at is the time of that check.

  • checked_at (required): string, format: date-time

  • checks (required): array of Check

  • credits_charged (required): integer, possible values: 0, 1

    Credits of the type of mode charged for this result.

  • email (required): string

    The address as verified, trimmed and lower-cased.

  • flags (required): Flags

  • id (required): string, pattern: ^ver_[a-f0-9]{32}$

  • livemode (required): boolean

  • mode (required): string, possible values: "basic", "mailbox"

    basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

  • mx (required): array of MxRecord

    Mail servers of the domain, as resolved. Empty when DNS was not resolved.

  • object (required): string, possible values: "verification"

  • reason (required): string

    Human-readable explanation of reason_code, in the language of Accept-Language.

  • reason_code (required): string

    Stable reason for the verdict. New values may be added.

    Code Verdict Mode Meaning
    syntax_invalid invalid both Not a valid address in the supported ASCII profile.
    address_unsupported unknown both Internationalised (non-ASCII) address; not checked.
    domain_not_found invalid both The domain does not exist (NXDOMAIN).
    domain_null_mx invalid both The domain declares it accepts no mail (null MX, RFC 7505).
    domain_no_mail_host invalid both No MX and no A/AAAA record.
    dns_temporary unknown both DNS failed temporarily. Not charged.
    mailbox_not_checked unknown basic Domain can receive mail; mailbox not probed.
    disposable_domain risky both Domain is on the disposable list.
    legacy_domain risky both Domain of a discontinued provider.
    mailbox_exists valid mailbox Recipient accepted, random control rejected.
    mailbox_not_found invalid mailbox Server says the recipient does not exist.
    mailbox_disabled risky mailbox Server says the mailbox is disabled.
    mailbox_full risky mailbox Server says the mailbox is full.
    mailbox_forwarded risky mailbox Server announces forwarding (251).
    provider_directory_rejected risky mailbox Provider directory rejection (Microsoft 365) without confirmation.
    catch_all risky mailbox Server also accepts a random recipient.
    catch_all_unresolved unknown mailbox Recipient accepted but the catch-all control was inconclusive.
    rejection_unconfirmed unknown mailbox Rejected, but a known-good control was rejected too.
    probe_rate_limited unknown mailbox Our hourly probe quota for that domain or server is exhausted.
    probe_blocked unknown mailbox The server refuses our probe (IP reputation, reverse DNS or sender policy).
    smtp_temporary unknown mailbox Temporary rejection or greylisting.
    smtp_unreachable unknown mailbox No mail server could be reached.
    smtp_tls_failed unknown mailbox The advertised TLS session could not be verified.
    smtp_rejected unknown mailbox Ambiguous or policy rejection that does not prove the mailbox is missing.
  • retry_at (required): string | null, format: date-time

    When a temporary result can be verified again. In batches this is handled for you.

  • smtp (required): SmtpEvidence | null

    null in basic mode or when the probe did not run.

  • verdict (required): string, possible values: "valid", "invalid", "risky", "unknown"

Generated example:

JSON
{
  "id": "",
  "object": "verification",
  "livemode": true,
  "email": "",
  "mode": "basic",
  "verdict": "valid",
  "reason_code": "mailbox_exists",
  "reason": "",
  "flags": {
    "disposable": true,
    "free": true,
    "catch_all": null
  },
  "checks": [
    {
      "name": "syntax",
      "status": ""
    }
  ],
  "mx": [
    {
      "host": "",
      "preference": 0
    }
  ],
  "smtp": {
    "mx": null,
    "code": null,
    "enhanced_code": null,
    "tls": true
  },
  "cached": true,
  "credits_charged": 0,
  "checked_at": "2026-11-17T09:50:00.000Z",
  "retry_at": null
}

VerifyRequest

Type: object

  • email (required): string, minLength: 1, maxLength: 1024

    Address to verify. Leading/trailing spaces and case are normalised.

  • mode: string, possible values: "basic", "mailbox", default: "basic"

    basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

Generated example:

JSON
{
  "email": "",
  "mode": "basic"
}

BatchCreateRequest

Type: object

  • emails (required): array, minItems: 1, maxItems: 10000

    Items:

    string, maxLength: 1024

  • mode: string, possible values: "basic", "mailbox", default: "basic"

    basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

  • name: string, maxLength: 120

    Optional label shown in the dashboard.

Generated example:

JSON
{
  "emails": [
    ""
  ],
  "mode": "basic",
  "name": ""
}

BatchCsvUpload

Type: object

  • file (required): string

    UTF-8 CSV with a header row. Up to 10 MB and 100,000 data rows.

  • delimiter: string, possible values: "comma", "semicolon", "tab", default: "comma"

  • email_column: string, default: "email"

    Exact name of the header that holds the addresses.

  • mode: string, possible values: "basic", "mailbox", default: "basic"

    basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

  • name: string, maxLength: 120

    Optional label shown in the dashboard.

Generated example:

JSON
{
  "file": "",
  "mode": "basic",
  "email_column": "email",
  "delimiter": "comma",
  "name": ""
}

BatchStatus

Type: string, possible values: "queued", "processing", "completed", "canceled", "failed"

queued → processing → completed. canceled after POST /batches/{batch_id}/cancel. failed only for an internal error; reserved credits are returned.

Batch

Type: object

  • created_at (required): string, format: date-time

  • credits (required): object

    • charged (required): integer

      Credits charged so far.

    • reserved (required): integer

      Credits still held for rows without a final result.

    • type (required): string, possible values: "basic", "mailbox"

      basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

  • deadline_at (required): string | null, format: date-time

    Processing deadline (6 days after start). Rows unresolved by then end as unknown, free of charge.

  • finished_at (required): string | null, format: date-time

    When the batch reached completed, canceled or failed.

  • id (required): string, pattern: ^bat_[a-f0-9]{32}$

  • livemode (required): boolean

  • mode (required): string, possible values: "basic", "mailbox"

    basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

  • name (required): string | null

  • object (required): string, possible values: "batch"

  • processed (required): integer

    Rows with a final result.

  • results_expire_at (required): string | null, format: date-time

    When inputs and results are deleted (30 days after finished_at).

  • source (required): string, possible values: "json", "csv"

  • started_at (required): string | null, format: date-time

  • status (required): string, possible values: "queued", "processing", "completed", "canceled", "failed"

    queued → processing → completed. canceled after POST /batches/{batch_id}/cancel. failed only for an internal error; reserved credits are returned.

  • summary (required): object

    Final results so far, by verdict (rows, including duplicates).

    • invalid (required): integer
    • risky (required): integer
    • unknown (required): integer
    • valid (required): integer
  • total (required): integer

    Rows accepted, including duplicates.

  • unique (required): integer

    Distinct addresses after normalisation.

Generated example:

JSON
{
  "id": "",
  "object": "batch",
  "livemode": true,
  "name": null,
  "source": "json",
  "mode": "basic",
  "status": "queued",
  "total": 1,
  "unique": 1,
  "processed": 1,
  "summary": {
    "valid": 1,
    "invalid": 1,
    "risky": 1,
    "unknown": 1
  },
  "credits": {
    "type": "basic",
    "reserved": 1,
    "charged": 1
  },
  "created_at": "2026-11-17T09:50:00.000Z",
  "started_at": null,
  "finished_at": null,
  "deadline_at": null,
  "results_expire_at": null
}

BatchList

Type: object

  • data (required): array of Batch
  • has_more (required): boolean
  • next_cursor (required): string | null
  • object (required): string, possible values: "list"

Generated example:

JSON
{
  "object": "list",
  "data": [
    {
      "id": "",
      "object": "batch",
      "livemode": true,
      "name": null,
      "source": "json",
      "mode": "basic",
      "status": "queued",
      "total": 1,
      "unique": 1,
      "processed": 1,
      "summary": {
        "valid": 1,
        "invalid": 1,
        "risky": 1,
        "unknown": 1
      },
      "credits": {
        "type": "basic",
        "reserved": 1,
        "charged": 1
      },
      "created_at": "2026-11-17T09:50:00.000Z",
      "started_at": null,
      "finished_at": null,
      "deadline_at": null,
      "results_expire_at": null
    }
  ],
  "has_more": true,
  "next_cursor": null
}

BatchResult

All of:

  • object
    • duplicate (required): boolean

      true when an earlier row holds the same address; duplicates are never charged.

    • input (required): string

      The value exactly as submitted.

    • row (required): integer, minimum: 1

      1-based position in emails, or data row number in the CSV (header excluded).

  • Verification

BatchResultList

Type: object

  • data (required): array of BatchResult
  • has_more (required): boolean
  • next_cursor (required): string | null
  • object (required): string, possible values: "list"

Generated example:

JSON
{
  "object": "list",
  "data": [
    {
      "row": 1,
      "input": "",
      "duplicate": true,
      "id": "",
      "object": "verification",
      "livemode": true,
      "email": "",
      "mode": "basic",
      "verdict": "valid",
      "reason_code": "mailbox_exists",
      "reason": "",
      "flags": {
        "disposable": true,
        "free": true,
        "catch_all": null
      },
      "checks": [
        {
          "name": "syntax",
          "status": ""
        }
      ],
      "mx": [
        {
          "host": "",
          "preference": 0
        }
      ],
      "smtp": {
        "mx": null,
        "code": null,
        "enhanced_code": null,
        "tls": true
      },
      "cached": true,
      "credits_charged": 0,
      "checked_at": "2026-11-17T09:50:00.000Z",
      "retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": null
}

Usage

Type: object

  • credits (required): object

    • basic (required): object
      • granted (required): integer

        Monthly allowance of the current period.

      • remaining (required): integer

      • reserved (required): integer

        Held by running batches.

      • resets_at (required): string, format: date-time

    • mailbox (required): object
      • next_expiry (required): object | null

        The next credits to expire, or null when none expire.

        • amount (required): integer
        • at (required): string, format: date-time
      • remaining (required): integer

      • reserved (required): integer

        Held by running batches.

  • livemode (required): boolean

  • object (required): string, possible values: "usage"

  • period (required): object

    Current billing period of the basic allowance.

    • end (required): string, format: date-time
    • start (required): string, format: date-time
  • usage (required): object

    Activity in the current period.

Generated example:

JSON
{
  "object": "usage",
  "livemode": true,
  "credits": {
    "basic": {
      "remaining": 1,
      "reserved": 1,
      "granted": 1,
      "resets_at": "2026-11-17T09:50:00.000Z"
    },
    "mailbox": {
      "remaining": 1,
      "reserved": 1,
      "next_expiry": {
        "amount": 1,
        "at": "2026-11-17T09:50:00.000Z"
      }
    }
  },
  "period": {
    "start": "2026-11-17T09:50:00.000Z",
    "end": "2026-11-17T09:50:00.000Z"
  },
  "usage": {
    "basic": {
      "verifications": 1,
      "credits_charged": 1
    },
    "mailbox": {
      "verifications": 1,
      "credits_charged": 1
    }
  }
}

UsageCounters

Type: object

  • credits_charged (required): integer

  • verifications (required): integer

    Verifications completed, single and batch.

Generated example:

JSON
{
  "verifications": 1,
  "credits_charged": 1
}

Account

Type: object

  • api_key (required): object

    The key used for this request. The secret is never returned.

    • created_at (required): string, format: date-time

    • id (required): string, pattern: ^key_[a-f0-9]{16}$

    • name (required): string

    • prefix (required): string

      First characters of the key, as shown in the dashboard.

  • created_at (required): string, format: date-time

  • id (required): string, pattern: ^org_[a-f0-9]{16}$

  • limits (required): object

    • max_batch_size (required): integer

      Maximum rows per batch for this plan.

    • max_concurrent_batches (required): integer

      Batches that may be queued or processing at once.

    • modes (required): array

      Items:

      string, possible values: "basic", "mailbox"

      basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

    • requests_per_minute (required): integer

  • livemode (required): boolean

    false when the request used a sk_test_… key.

  • name (required): string

  • object (required): string, possible values: "account"

  • plan (required): object

    • id (required): string, possible values: "free", "basic", "basic_plus"
    • status (required): string, possible values: "active", "past_due", "canceled"

Generated example:

JSON
{
  "id": "",
  "object": "account",
  "livemode": true,
  "name": "",
  "plan": {
    "id": "free",
    "status": "active"
  },
  "api_key": {
    "id": "",
    "name": "",
    "prefix": "",
    "created_at": "2026-11-17T09:50:00.000Z"
  },
  "limits": {
    "requests_per_minute": 1,
    "max_batch_size": 1,
    "max_concurrent_batches": 1,
    "modes": [
      "basic"
    ]
  },
  "created_at": "2026-11-17T09:50:00.000Z"
}

Error

Type: object

  • code (required): string

    Stable machine-readable code (see the table in the API description). New values may be added.

  • message (required): string

    Human-readable explanation. Do not parse it.

  • request_id (required): string

    Same value as the X-Request-Id header.

  • type (required): string, possible values: "invalid_request", "authentication", "payment_required", "permission", "not_found", "conflict", "rate_limit", "api_error"

  • param: string

    Request field the error refers to, when there is one.

Generated example:

JSON
{
  "type": "invalid_request",
  "code": "",
  "message": "",
  "param": "",
  "request_id": ""
}

ErrorResponse

Type: object

  • error (required): Error

Generated example:

JSON
{
  "error": {
    "type": "invalid_request",
    "code": "",
    "message": "",
    "param": "",
    "request_id": ""
  }
}

EventBase

Type: object

  • created_at (required): string, format: date-time

  • id (required): string, pattern: ^evt_[a-f0-9]{32}$

    Unique per event; identical across retries. Use it to deduplicate.

  • livemode (required): boolean

  • object (required): string, possible values: "event"

  • type (required): string

Generated example:

JSON
{
  "id": "",
  "object": "event",
  "type": "",
  "livemode": true,
  "created_at": "2026-11-17T09:50:00.000Z"
}

BatchCompletedEvent

All of:

  • EventBase
  • object
    • data (required): object
      • batch (required): Batch
    • type (required): string, possible values: "batch.completed"

CreditsLowEvent

All of:

  • EventBase
  • object
    • data (required): object
      • credit_type (required): string, possible values: "basic", "mailbox"

        basic: syntax, domain lists and DNS (1 basic credit). mailbox: adds the SMTP mailbox probe (1 mailbox credit, charged only when the verdict is not unknown).

      • remaining (required): integer

      • threshold (required): integer

    • type (required): string, possible values: "credits.low"