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).
- OpenAPI Version:
3.2.0 - API Version:
1.0.0 - Terms of service: https://salchimail.com/terms
- Contact: SalchiMail support https://docs.salchimail.com hola@salchimail.com
- License: SalchiMail API Terms
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 |
basicnever contacts the mail server, so a deliverable domain yieldsunknown(mailbox_not_checked) orrisky(list signal), nevervalid.basic: every completed verification costs 1 basic credit, exceptdns_temporaryresults and repeats of the same address within 30 days.mailbox: 1 mailbox credit only when the verdict is notunknown. 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_chargedon 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
- POST /verify
- POST /batches
- GET /batches
- GET /batches/{batch_id}
- GET /batches/{batch_id}/results
- POST /batches/{batch_id}/cancel
- GET /usage
- GET /account
Webhooks
Schemas
- Mode
- Verdict
- ReasonCode
- Check
- Flags
- MxRecord
- SmtpEvidence
- Verification
- VerifyRequest
- BatchCreateRequest
- BatchCsvUpload
- BatchStatus
- Batch
- BatchList
- BatchResult
- BatchResultList
- Usage
- UsageCounters
- Account
- Error
- ErrorResponse
- EventBase
- BatchCompletedEvent
- CreditsLowEvent
Servers
- URL:
https://api.salchimail.com/v1- Description: Production
Authentication
bearerAuth: HTTP bearer (
API key)Secret API key:
sk_live_…(live) orsk_test_…(test mode). Send it asAuthorization: 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:255Unique 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
reasonand errormessage.en(default) ores.Example:
JSON "es"
Request body
Required: true
Content type: application/json
Example: basic
Without mailbox check (1 basic credit)
{
"email": "ana@example.com"
}Example: mailbox
With SMTP mailbox check (1 mailbox credit)
{
"email": "ana@example.com",
"mode": "mailbox"
}Responses
200 Verification result.
Headers:
X-Request-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42Idempotent-ReplayedPresent and
truewhen the response was replayed for a repeatedIdempotency-Key.booleanExample:
JSON true
Content type: application/json
Example: basicUnknown
basic mode, domain can receive mail
{
"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
{
"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)
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: missingParameter
Required field missing
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: insufficientCredits
No mailbox credits left
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: modeNotAllowed
Mode not available to this account
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: keyReused
Same key, different body
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: unsupported
Wrong Content-Type
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12
Content type: application/json
Example: timeout
Mailbox check did not finish in time
{
"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-datawith a UTF-8 file of up to 10 MB and 100,000 data rows. A header row is required andemail_columnmust match one column name exactly. Only that column is stored; other columns are discarded. Join results back byrow.
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:255Unique 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
Example: json
JSON list with mailbox check
{
"emails": [
"ana@example.com",
"luis@example.org",
"not-an-email"
],
"mode": "mailbox",
"name": "November newsletter"
}Content type: multipart/form-data
Example: csv
CSV upload (fields of the multipart form)
{
"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
- Content-Type:
Responses
202 Batch accepted and queued.
Headers:
LocationURL of the new batch.
string, format:uriExample:
JSON "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"X-Request-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42Idempotent-ReplayedPresent and
truewhen the response was replayed for a repeatedIdempotency-Key.booleanExample:
JSON true
Content type: application/json
Example: queued
Batch just created
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: missingParameter
Required field missing
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: insufficientCredits
No mailbox credits left
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: modeNotAllowed
Mode not available to this account
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: keyReused
Same key, different body
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: tooLarge
CSV over 10 MB
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: unsupported
Wrong Content-Type
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12
Content type: application/json
Example: timeout
Mailbox check did not finish in time
{
"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:100Page size.
Example:
JSON 20cursor:string, maxLength:255Opaque
next_cursorfrom the previous page.Example:
JSON "eyJyb3ciOjN9"
Responses
200 A page of batches.
Headers:
X-Request-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: page
One completed batch
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: missingParameter
Required field missing
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: processing
Batch in progress
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: notFound
Unknown batch
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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:10000Page size. Maximum 1,000 for JSON and 10,000 for CSV.
Example:
JSON 100cursor:string, maxLength:255Opaque
next_cursorfrom the previous page.Example:
JSON "eyJyb3ciOjN9"
Header parameters
Accept-Language:string, default:"en"Language of
reasonand errormessage.en(default) ores.Example:
JSON "es"
Responses
200 A page of results.
Headers:
LinkNext page as
<url>; rel="next". Absent on the last page.stringExample:
JSON "<https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?format=csv&cursor=eyJyb3ciOjN9>; rel=\"next\""X-Request-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: page
Two rows, more available
{
"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
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: missingParameter
Required field missing
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: notFound
Unknown batch
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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:255Unique 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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42Idempotent-ReplayedPresent and
truewhen the response was replayed for a repeatedIdempotency-Key.booleanExample:
JSON true
Content type: application/json
Example: canceled
Canceled after two results
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: notFound
Unknown batch
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: keyReused
Same key, different body
{
"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
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: usage
Basic plan with a mailbox pack
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: account
Organisation on the Basic plan
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"WWW-AuthenticateAlways
Bearer.stringExample:
JSON "Bearer"
Content type: application/json
Example: invalidKey
Unknown key
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"Retry-AfterSeconds to wait before retrying.
integerExample:
JSON 12RateLimit-LimitRequests allowed in the current window.
integerExample:
JSON 600RateLimit-RemainingRequests left in the current window.
integerExample:
JSON 598RateLimit-ResetSeconds until the current window resets.
integerExample:
JSON 42
Content type: application/json
Example: rateLimited
Too many requests
{
"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-IdIdentifier of this request; the same value as
error.request_id.stringExample:
JSON "req_4b5c6d7e8f9a0b1c"
Content type: application/json
Example: internal
Internal error
{
"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):stringt=<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
Example: completed
Batch completed
{
"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):stringt=<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
Example: low
Mailbox credits running low
{
"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:
"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):stringOutcome of the step. New values may be added.
Generated example:
{
"name": "syntax",
"status": ""
}Flags
Type: object
catch_all(required):boolean | nulltrue: the server also accepted a random recipient.false: it rejected the random recipient.null: not tested (basicmode, recipient not accepted) or inconclusive.disposable(required):booleanThe domain (or a parent domain) is on the disposable-email list.
free(required):booleanThe domain is a free webmail provider. Informational; does not change the verdict.
Generated example:
{
"disposable": true,
"free": true,
"catch_all": null
}MxRecord
Type: object
host(required):stringpreference(required):integer, minimum:0, maximum:65535
Generated example:
{
"host": "",
"preference": 0
}SmtpEvidence
Type: object
What the recipient's server answered to RCPT TO for this address.
code(required):integer | nullSMTP reply code, when a reply was received.
enhanced_code(required):string | nullEnhanced status code (RFC 3463), when present.
mx(required):string | nullMail server that answered.
tls(required):booleanWhether the session used verified TLS.
Generated example:
{
"mx": null,
"code": null,
"enhanced_code": null,
"tls": true
}Verification
Type: object
cached(required):booleanThe result was served from a recent check;
checked_atis the time of that check.checked_at(required):string, format:date-timechecks(required): array of Checkcredits_charged(required):integer, possible values:0, 1Credits of the type of
modecharged for this result.email(required):stringThe address as verified, trimmed and lower-cased.
flags(required): Flagsid(required):string, pattern:^ver_[a-f0-9]{32}$livemode(required):booleanmode(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 notunknown).mx(required): array of MxRecordMail servers of the domain, as resolved. Empty when DNS was not resolved.
object(required):string, possible values:"verification"reason(required):stringHuman-readable explanation of
reason_code, in the language ofAccept-Language.reason_code(required):stringStable reason for the verdict. New values may be added.
Code Verdict Mode Meaning syntax_invalidinvalid both Not a valid address in the supported ASCII profile. address_unsupportedunknown both Internationalised (non-ASCII) address; not checked. domain_not_foundinvalid both The domain does not exist (NXDOMAIN). domain_null_mxinvalid both The domain declares it accepts no mail (null MX, RFC 7505). domain_no_mail_hostinvalid both No MX and no A/AAAA record. dns_temporaryunknown both DNS failed temporarily. Not charged. mailbox_not_checkedunknown basic Domain can receive mail; mailbox not probed. disposable_domainrisky both Domain is on the disposable list. legacy_domainrisky both Domain of a discontinued provider. mailbox_existsvalid mailbox Recipient accepted, random control rejected. mailbox_not_foundinvalid mailbox Server says the recipient does not exist. mailbox_disabledrisky mailbox Server says the mailbox is disabled. mailbox_fullrisky mailbox Server says the mailbox is full. mailbox_forwardedrisky mailbox Server announces forwarding (251). provider_directory_rejectedrisky mailbox Provider directory rejection (Microsoft 365) without confirmation. catch_allrisky mailbox Server also accepts a random recipient. catch_all_unresolvedunknown mailbox Recipient accepted but the catch-all control was inconclusive. rejection_unconfirmedunknown mailbox Rejected, but a known-good control was rejected too. probe_rate_limitedunknown mailbox Our hourly probe quota for that domain or server is exhausted. probe_blockedunknown mailbox The server refuses our probe (IP reputation, reverse DNS or sender policy). smtp_temporaryunknown mailbox Temporary rejection or greylisting. smtp_unreachableunknown mailbox No mail server could be reached. smtp_tls_failedunknown mailbox The advertised TLS session could not be verified. smtp_rejectedunknown mailbox Ambiguous or policy rejection that does not prove the mailbox is missing. retry_at(required):string | null, format:date-timeWhen a temporary result can be verified again. In batches this is handled for you.
smtp(required): SmtpEvidence |nullnullinbasicmode or when the probe did not run.verdict(required):string, possible values:"valid", "invalid", "risky", "unknown"
Generated example:
{
"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:1024Address 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 notunknown).
Generated example:
{
"email": "",
"mode": "basic"
}BatchCreateRequest
Type: object
emails(required):array, minItems:1, maxItems:10000Items:
string, maxLength:1024mode: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 notunknown).name:string, maxLength:120Optional label shown in the dashboard.
Generated example:
{
"emails": [
""
],
"mode": "basic",
"name": ""
}BatchCsvUpload
Type: object
file(required):stringUTF-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 notunknown).name:string, maxLength:120Optional label shown in the dashboard.
Generated example:
{
"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-timecredits(required):objectcharged(required):integerCredits charged so far.
reserved(required):integerCredits 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 notunknown).
deadline_at(required):string | null, format:date-timeProcessing deadline (6 days after start). Rows unresolved by then end as
unknown, free of charge.finished_at(required):string | null, format:date-timeWhen the batch reached
completed,canceledorfailed.id(required):string, pattern:^bat_[a-f0-9]{32}$livemode(required):booleanmode(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 notunknown).name(required):string | nullobject(required):string, possible values:"batch"processed(required):integerRows with a final result.
results_expire_at(required):string | null, format:date-timeWhen inputs and results are deleted (30 days after
finished_at).source(required):string, possible values:"json", "csv"started_at(required):string | null, format:date-timestatus(required):string, possible values:"queued", "processing", "completed", "canceled", "failed"queued→processing→completed.canceledafterPOST /batches/{batch_id}/cancel.failedonly for an internal error; reserved credits are returned.summary(required):objectFinal results so far, by verdict (rows, including duplicates).
invalid(required):integerrisky(required):integerunknown(required):integervalid(required):integer
total(required):integerRows accepted, including duplicates.
unique(required):integerDistinct addresses after normalisation.
Generated example:
{
"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 Batchhas_more(required):booleannext_cursor(required):string | nullobject(required):string, possible values:"list"
Generated example:
{
"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:
objectduplicate(required):booleantruewhen an earlier row holds the same address; duplicates are never charged.input(required):stringThe value exactly as submitted.
row(required):integer, minimum:11-based position in
emails, or data row number in the CSV (header excluded).
- Verification
BatchResultList
Type: object
data(required): array of BatchResulthas_more(required):booleannext_cursor(required):string | nullobject(required):string, possible values:"list"
Generated example:
{
"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):objectbasic(required):objectgranted(required):integerMonthly allowance of the current period.
remaining(required):integerreserved(required):integerHeld by running batches.
resets_at(required):string, format:date-time
mailbox(required):objectnext_expiry(required):object | nullThe next credits to expire, or
nullwhen none expire.amount(required):integerat(required):string, format:date-time
remaining(required):integerreserved(required):integerHeld by running batches.
livemode(required):booleanobject(required):string, possible values:"usage"period(required):objectCurrent billing period of the basic allowance.
end(required):string, format:date-timestart(required):string, format:date-time
usage(required):objectActivity in the current period.
basic(required): UsageCountersmailbox(required): UsageCounters
Generated example:
{
"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):integerverifications(required):integerVerifications completed, single and batch.
Generated example:
{
"verifications": 1,
"credits_charged": 1
}Account
Type: object
api_key(required):objectThe key used for this request. The secret is never returned.
created_at(required):string, format:date-timeid(required):string, pattern:^key_[a-f0-9]{16}$name(required):stringprefix(required):stringFirst characters of the key, as shown in the dashboard.
created_at(required):string, format:date-timeid(required):string, pattern:^org_[a-f0-9]{16}$limits(required):objectmax_batch_size(required):integerMaximum rows per batch for this plan.
max_concurrent_batches(required):integerBatches that may be
queuedorprocessingat once.modes(required):arrayItems:
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 notunknown).requests_per_minute(required):integer
livemode(required):booleanfalsewhen the request used ask_test_…key.name(required):stringobject(required):string, possible values:"account"plan(required):objectid(required):string, possible values:"free", "basic", "basic_plus"status(required):string, possible values:"active", "past_due", "canceled"
Generated example:
{
"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):stringStable machine-readable code (see the table in the API description). New values may be added.
message(required):stringHuman-readable explanation. Do not parse it.
request_id(required):stringSame value as the
X-Request-Idheader.type(required):string, possible values:"invalid_request", "authentication", "payment_required", "permission", "not_found", "conflict", "rate_limit", "api_error"param:stringRequest field the error refers to, when there is one.
Generated example:
{
"type": "invalid_request",
"code": "",
"message": "",
"param": "",
"request_id": ""
}ErrorResponse
Type: object
error(required): Error
Generated example:
{
"error": {
"type": "invalid_request",
"code": "",
"message": "",
"param": "",
"request_id": ""
}
}EventBase
Type: object
created_at(required):string, format:date-timeid(required):string, pattern:^evt_[a-f0-9]{32}$Unique per event; identical across retries. Use it to deduplicate.
livemode(required):booleanobject(required):string, possible values:"event"type(required):string
Generated example:
{
"id": "",
"object": "event",
"type": "",
"livemode": true,
"created_at": "2026-11-17T09:50:00.000Z"
}BatchCompletedEvent
All of:
- EventBase
objectdata(required):objectbatch(required): Batch
type(required):string, possible values:"batch.completed"
CreditsLowEvent
All of:
- EventBase
objectdata(required):objectcredit_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 notunknown).remaining(required):integerthreshold(required):integer
type(required):string, possible values:"credits.low"