{
  "openapi": "3.1.0",
  "info": {
    "title": "SalchiMail API",
    "version": "1.0.0",
    "summary": "Email verification without sending email.",
    "termsOfService": "https://salchimail.com/terms",
    "contact": {
      "name": "SalchiMail support",
      "url": "https://docs.salchimail.com",
      "email": "hola@salchimail.com"
    },
    "license": {
      "name": "SalchiMail API Terms",
      "url": "https://salchimail.com/terms"
    },
    "description": "Verify email addresses one at a time or in batches. SalchiMail never sends\nemail: mailbox checks stop at `RCPT TO` and never issue `DATA`.\n\n## Authentication\n\nSend your secret key on every request: `Authorization: Bearer sk_live_…`.\nKeys are created in the dashboard (`https://app.salchimail.com`), shown once\nand stored only as a hash. Keys are secrets: use them from servers, never\nfrom browsers or mobile apps.\n\n`sk_test_…` keys run in **test mode**: no real verification is performed and\nno credits are used. Syntax is still checked; the verdict is chosen by the\nlocal part of the address: `valid@…` → `valid`, `invalid@…` → `invalid`,\n`risky@…` → `risky` (`catch_all`), `disposable@…` → `risky`\n(`disposable_domain`), anything else → `unknown`. Test batches complete\nwithin seconds. Test objects carry `livemode: false`.\n\n## Modes and credits\n\n| `mode` | What it checks | Credit used | Can return `valid` |\n| --- | --- | --- | --- |\n| `basic` | Syntax, domain lists (disposable, free), DNS/MX | 1 **basic** credit | No |\n| `mailbox` | Everything in `basic` + SMTP `RCPT TO` probe and catch-all control | 1 **mailbox** credit | Yes |\n\n- `basic` never contacts the mail server, so a deliverable domain yields\n  `unknown` (`mailbox_not_checked`) or `risky` (list signal), never `valid`.\n- `basic`: every completed verification costs 1 basic credit, except\n  `dns_temporary` results and repeats of the same address within 30 days.\n- `mailbox`: 1 mailbox credit **only when the verdict is not `unknown`**.\n  Repeats of the same address within 24 hours and duplicates inside a batch\n  are free.\n- The two balances are independent: one never pays for the other.\n- `credits_charged` on every result tells you exactly what was charged.\n- With no credits left the API answers `402 insufficient_credits`.\n\n## Verdicts\n\n| Verdict | Meaning |\n| --- | --- |\n| `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. |\n| `invalid` | Unsupported syntax, a domain that cannot receive mail, or an unambiguous \"no such recipient\" rejection. |\n| `risky` | Accept-all server, disposable or legacy domain, forwarding, full or disabled mailbox, or a provider directory rejection without confirmation. |\n| `unknown` | Mailbox not checked (`basic`), timeout, greylisting, temporary DNS or SMTP failure, probe quota, ambiguous answer. |\n\nDo not treat `unknown` as `invalid`. A result with `retry_at` can be\nverified again after that time.\n\n## Rate limits\n\nLimits depend on the plan and are reported by `GET /account`. Every response\ncarries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`\n(seconds until the window resets). Over the limit the API answers `429` with\n`Retry-After`.\n\n## Idempotency\n\n`POST` operations accept an `Idempotency-Key` header (any unique string up\nto 255 characters, a UUID is recommended). Keys are kept 24 hours per\naccount. A retry with the same key and the same body returns the stored\nresponse with `Idempotent-Replayed: true` and charges nothing. The same key\nwith a different body returns `409 idempotency_key_reused`; a retry while\nthe first request is still running returns `409 idempotency_in_progress`.\n\n## Errors\n\nEvery error uses one shape: `{\"error\": {\"type\", \"code\", \"message\", \"request_id\"}}`.\n`type` is the broad class, `code` is stable and machine-readable, `message`\nis for humans (localised with `Accept-Language`: `en` default, `es`).\n`request_id` equals the `X-Request-Id` response header; quote it to support.\n\n| HTTP | `type` | `code` |\n| --- | --- | --- |\n| 400 | `invalid_request` | `invalid_json`, `missing_parameter`, `invalid_parameter`, `batch_empty`, `batch_too_large`, `csv_invalid`, `csv_column_not_found` |\n| 401 | `authentication` | `missing_api_key`, `invalid_api_key`, `revoked_api_key` |\n| 402 | `payment_required` | `insufficient_credits` |\n| 403 | `permission` | `mode_not_allowed`, `account_suspended` |\n| 404 | `not_found` | `not_found` |\n| 409 | `conflict` | `idempotency_key_reused`, `idempotency_in_progress`, `batch_not_cancelable` |\n| 413 | `invalid_request` | `payload_too_large` |\n| 415 | `invalid_request` | `unsupported_media_type` |\n| 429 | `rate_limit` | `rate_limit_exceeded`, `concurrent_batches_exceeded` |\n| 500 | `api_error` | `internal_error` |\n| 503 | `api_error` | `engine_unavailable`, `verification_timeout` |\n\nNew `code` and `reason_code` values may be added without a version bump:\ntreat unknown values as their `type` or `verdict`.\n\n## Webhooks\n\nEndpoints are configured in the dashboard. Each delivery is a `POST` with a\nJSON event and the header\n`SalchiMail-Signature: t=<unix seconds>,v1=<hex>`, where `v1` is\n`HMAC-SHA256(endpoint_secret, \"<t>.<raw request body>\")`. Verify it with a\nconstant-time comparison against the raw body and reject timestamps older\nthan 5 minutes. During secret rotation several `v1` values may be present:\naccept if any matches. Answer `2xx` within 10 seconds; anything else is\nretried with exponential backoff for up to 24 hours (8 attempts). Deliveries\ncan arrive more than once or out of order: deduplicate by event `id`.\n\n## Data retention\n\nBatch inputs and results are deleted 30 days after the batch finishes.\nSingle verifications are not stored in readable form.\n"
  },
  "servers": [
    {
      "url": "https://api.salchimail.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Verification",
      "description": "Verify one address synchronously."
    },
    {
      "name": "Batches",
      "description": "Verify lists asynchronously from JSON or CSV and download results."
    },
    {
      "name": "Usage",
      "description": "Remaining credits and usage for the current period."
    },
    {
      "name": "Account",
      "description": "The account, plan and limits behind the API key."
    },
    {
      "name": "Webhooks",
      "description": "Signed events SalchiMail sends to your endpoints."
    }
  ],
  "paths": {
    "/verify": {
      "post": {
        "operationId": "verifyEmail",
        "tags": [
          "Verification"
        ],
        "summary": "Verify one email address",
        "description": "Runs a verification and returns the result in the same response.\n`basic` normally answers in well under a second. `mailbox` talks to the\nrecipient's mail server and can take up to 30 seconds; if it cannot\nfinish in time the API answers `503 verification_timeout` and charges\nnothing. For more than a few addresses use batches.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              },
              "examples": {
                "basic": {
                  "summary": "Without mailbox check (1 basic credit)",
                  "value": {
                    "email": "ana@example.com"
                  }
                },
                "mailbox": {
                  "summary": "With SMTP mailbox check (1 mailbox credit)",
                  "value": {
                    "email": "ana@example.com",
                    "mode": "mailbox"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Verification"
                },
                "examples": {
                  "basicUnknown": {
                    "summary": "basic mode, domain can receive mail",
                    "value": {
                      "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
                    }
                  },
                  "mailboxValid": {
                    "summary": "mailbox mode, recipient accepted and control rejected",
                    "value": {
                      "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
                    }
                  },
                  "mailboxDeferred": {
                    "summary": "mailbox mode, greylisted (not charged)",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/batches": {
      "post": {
        "operationId": "createBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Create a batch from JSON or CSV",
        "description": "Queues a list for asynchronous verification and returns `202` at once.\n\n- **JSON**: up to 10,000 addresses in `emails`.\n- **CSV**: `multipart/form-data` with a UTF-8 file of up to 10 MB and\n  100,000 data rows. A header row is required and `email_column` must\n  match one column name exactly. Only that column is stored; other\n  columns are discarded. Join results back by `row`.\n\nYour plan may set a lower limit (`limits.max_batch_size` in\n`GET /account`). Credits for every unique address are reserved when the\nbatch is created (`402` if the balance is too low) and unused credits\nare returned when it finishes. Duplicated addresses are verified once\nand charged once.\n\n`mailbox` batches respect per-domain and per-server probe quotas and\nretry deferred addresses, so large lists concentrated on a few domains\ncan take hours or days. Addresses still unresolved at `deadline_at`\nend as `unknown` and are not charged.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCreateRequest"
              },
              "examples": {
                "json": {
                  "summary": "JSON list with mailbox check",
                  "value": {
                    "emails": [
                      "ana@example.com",
                      "luis@example.org",
                      "not-an-email"
                    ],
                    "mode": "mailbox",
                    "name": "November newsletter"
                  }
                }
              }
            },
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/BatchCsvUpload"
              },
              "encoding": {
                "file": {
                  "contentType": "text/csv"
                }
              },
              "examples": {
                "csv": {
                  "summary": "CSV upload (fields of the multipart form)",
                  "value": {
                    "file": "id,email\n1,ana@example.com\n2,luis@example.org\n",
                    "mode": "mailbox",
                    "email_column": "email",
                    "delimiter": "comma",
                    "name": "November newsletter"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Batch accepted and queued.",
            "headers": {
              "Location": {
                "description": "URL of the new batch.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                },
                "example": "https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                },
                "examples": {
                  "queued": {
                    "$ref": "#/components/examples/BatchQueued"
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/PaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/PayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedMediaType"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      },
      "get": {
        "operationId": "listBatches",
        "tags": [
          "Batches"
        ],
        "summary": "List batches",
        "description": "Returns the account's batches, newest first.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/Cursor"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of batches.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchList"
                },
                "examples": {
                  "page": {
                    "summary": "One completed batch",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/batches/{batch_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BatchId"
        }
      ],
      "get": {
        "operationId": "getBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Get batch status",
        "description": "Poll this endpoint (every few seconds at most) or subscribe to the\n`batch.completed` webhook. `processed` grows as addresses reach a final\nresult.\n",
        "responses": {
          "200": {
            "description": "The batch.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                },
                "examples": {
                  "processing": {
                    "summary": "Batch in progress",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/batches/{batch_id}/results": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BatchId"
        }
      ],
      "get": {
        "operationId": "listBatchResults",
        "tags": [
          "Batches"
        ],
        "summary": "Get batch results (JSON or CSV)",
        "description": "Returns results ordered by `row`. Only rows with a final result are\nlisted, so pages requested while the batch is `processing` are partial:\nwait for a terminal status for a complete export. Rows never processed\nin a `canceled` batch are omitted.\n\nWith `format=csv` the body is CSV with the header\n`row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at`\nand the next page is given by the `Link` header (`rel=\"next\"`).\nResults are deleted at `results_expire_at`; after that this endpoint\nanswers `404`.\n",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "Response format.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "csv"
              ],
              "default": "json"
            },
            "example": "json"
          },
          {
            "name": "verdict",
            "in": "query",
            "description": "Only return rows with this verdict.",
            "schema": {
              "$ref": "#/components/schemas/Verdict"
            },
            "example": "valid"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size. Maximum 1,000 for JSON and 10,000 for CSV.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10000,
              "default": 100
            },
            "example": 100
          },
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of results.",
            "headers": {
              "Link": {
                "$ref": "#/components/headers/Link"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResultList"
                },
                "examples": {
                  "page": {
                    "summary": "Two rows, more available",
                    "value": {
                      "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"
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                },
                "examples": {
                  "page": {
                    "summary": "Same page as CSV",
                    "value": "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": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/batches/{batch_id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/BatchId"
        }
      ],
      "post": {
        "operationId": "cancelBatch",
        "tags": [
          "Batches"
        ],
        "summary": "Cancel a batch",
        "description": "Stops a `queued` or `processing` batch. Results already produced stay\navailable and charged; credits reserved for the rest are returned.\nCanceling a batch that is already `canceled` returns it unchanged; a\n`completed` or `failed` batch answers `409 batch_not_cancelable`.\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "The canceled batch.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/Idempotent-Replayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Batch"
                },
                "examples": {
                  "canceled": {
                    "summary": "Canceled after two results",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "getUsage",
        "tags": [
          "Usage"
        ],
        "summary": "Get remaining credits and current usage",
        "description": "`remaining` is what you can spend now; credits held by running batches\nare reported separately in `reserved`. Basic credits are a monthly\nallowance that resets at `resets_at` and does not roll over. Mailbox\ncredits come from one-off packs; credits closest to expiring are spent\nfirst.\n",
        "responses": {
          "200": {
            "description": "Credits and usage.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                },
                "examples": {
                  "usage": {
                    "summary": "Basic plan with a mailbox pack",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/account": {
      "get": {
        "operationId": "getAccount",
        "tags": [
          "Account"
        ],
        "summary": "Get the account behind the API key",
        "description": "Returns the organisation, its plan, the key in use and the limits that apply to it.",
        "responses": {
          "200": {
            "description": "The account.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/X-Request-Id"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                },
                "examples": {
                  "account": {
                    "summary": "Organisation on the Basic plan",
                    "value": {
                      "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": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "webhooks": {
    "batch.completed": {
      "post": {
        "operationId": "onBatchCompleted",
        "tags": [
          "Webhooks"
        ],
        "summary": "A batch finished",
        "description": "Sent when a batch reaches `completed` or `failed` (check\n`data.batch.status`). Not sent for batches you cancel. Fetch the rows\nwith `GET /batches/{batch_id}/results`.\n",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchCompletedEvent"
              },
              "examples": {
                "completed": {
                  "summary": "Batch completed",
                  "value": {
                    "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": {
            "description": "Acknowledged. Any `2xx` within 10 seconds stops retries."
          },
          "4XX": {
            "description": "Any non-2xx answer or a timeout schedules a retry."
          }
        }
      }
    },
    "credits.low": {
      "post": {
        "operationId": "onCreditsLow",
        "tags": [
          "Webhooks"
        ],
        "summary": "A credit balance fell below its threshold",
        "description": "Sent once each time a balance crosses the threshold configured in the\ndashboard (default: 10% of the last grant). It is sent again only after\nthe balance has been topped up above the threshold and falls below it\nagain.\n",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/WebhookSignature"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreditsLowEvent"
              },
              "examples": {
                "low": {
                  "summary": "Mailbox credits running low",
                  "value": {
                    "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": {
            "description": "Acknowledged. Any `2xx` within 10 seconds stops retries."
          },
          "4XX": {
            "description": "Any non-2xx answer or a timeout schedules a retry."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "Secret API key: `sk_live_…` (live) or `sk_test_…` (test mode). Send it\nas `Authorization: Bearer <key>`.\n"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "description": "Unique key that makes the request safe to retry for 24 hours.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "example": "6f1c1c0e-6d1f-4f0e-9f58-0d6b0a1c2e3f"
      },
      "AcceptLanguage": {
        "name": "Accept-Language",
        "in": "header",
        "description": "Language of `reason` and error `message`. `en` (default) or `es`.",
        "schema": {
          "type": "string",
          "default": "en"
        },
        "example": "es"
      },
      "BatchId": {
        "name": "batch_id",
        "in": "path",
        "required": true,
        "description": "Batch identifier.",
        "schema": {
          "type": "string",
          "pattern": "^bat_[a-f0-9]{32}$"
        },
        "example": "bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b"
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "description": "Page size.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        },
        "example": 20
      },
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "description": "Opaque `next_cursor` from the previous page.",
        "schema": {
          "type": "string",
          "maxLength": 255
        },
        "example": "eyJyb3ciOjN9"
      },
      "WebhookSignature": {
        "name": "SalchiMail-Signature",
        "in": "header",
        "required": true,
        "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\" with the\nendpoint secret>`.\n",
        "schema": {
          "type": "string"
        },
        "example": "t=1794909701,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"
      }
    },
    "headers": {
      "X-Request-Id": {
        "description": "Identifier of this request; the same value as `error.request_id`.",
        "schema": {
          "type": "string"
        },
        "example": "req_4b5c6d7e8f9a0b1c"
      },
      "RateLimit-Limit": {
        "description": "Requests allowed in the current window.",
        "schema": {
          "type": "integer"
        },
        "example": 600
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer"
        },
        "example": 598
      },
      "RateLimit-Reset": {
        "description": "Seconds until the current window resets.",
        "schema": {
          "type": "integer"
        },
        "example": 42
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer"
        },
        "example": 12
      },
      "Idempotent-Replayed": {
        "description": "Present and `true` when the response was replayed for a repeated `Idempotency-Key`.",
        "schema": {
          "type": "boolean"
        },
        "example": true
      },
      "Link": {
        "description": "Next page as `<url>; rel=\"next\"`. Absent on the last page.",
        "schema": {
          "type": "string"
        },
        "example": "<https://api.salchimail.com/v1/batches/bat_5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b/results?format=csv&cursor=eyJyb3ciOjN9>; rel=\"next\""
      }
    },
    "examples": {
      "BatchQueued": {
        "summary": "Batch just created",
        "value": {
          "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
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is malformed or a parameter is invalid.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missingParameter": {
                "summary": "Required field missing",
                "value": {
                  "error": {
                    "type": "invalid_request",
                    "code": "missing_parameter",
                    "message": "The email field is required.",
                    "param": "email",
                    "request_id": "req_4b5c6d7e8f9a0b1c"
                  }
                }
              },
              "batchTooLarge": {
                "summary": "Batch above the plan limit",
                "value": {
                  "error": {
                    "type": "invalid_request",
                    "code": "batch_too_large",
                    "message": "This plan accepts up to 100 addresses per batch.",
                    "param": "emails",
                    "request_id": "req_4b5c6d7e8f9a0b1d"
                  }
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key is missing, invalid or revoked.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          },
          "WWW-Authenticate": {
            "description": "Always `Bearer`.",
            "schema": {
              "type": "string"
            },
            "example": "Bearer"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "invalidKey": {
                "summary": "Unknown key",
                "value": {
                  "error": {
                    "type": "authentication",
                    "code": "invalid_api_key",
                    "message": "The API key is not valid.",
                    "request_id": "req_4b5c6d7e8f9a0b1e"
                  }
                }
              }
            }
          }
        }
      },
      "PaymentRequired": {
        "description": "Not enough credits of the type the request needs.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "insufficientCredits": {
                "summary": "No mailbox credits left",
                "value": {
                  "error": {
                    "type": "payment_required",
                    "code": "insufficient_credits",
                    "message": "This request needs 3 mailbox credits and the account has 0.",
                    "request_id": "req_4b5c6d7e8f9a0b1f"
                  }
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "The key is valid but the account may not do this.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "modeNotAllowed": {
                "summary": "Mode not available to this account",
                "value": {
                  "error": {
                    "type": "permission",
                    "code": "mode_not_allowed",
                    "message": "Mailbox verification is not enabled for this account.",
                    "param": "mode",
                    "request_id": "req_4b5c6d7e8f9a0b20"
                  }
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource does not exist, belongs to another account or has expired.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "notFound": {
                "summary": "Unknown batch",
                "value": {
                  "error": {
                    "type": "not_found",
                    "code": "not_found",
                    "message": "Batch not found.",
                    "request_id": "req_4b5c6d7e8f9a0b21"
                  }
                }
              }
            }
          }
        }
      },
      "Conflict": {
        "description": "Idempotency conflict or the resource is in a state that does not allow the operation.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "keyReused": {
                "summary": "Same key, different body",
                "value": {
                  "error": {
                    "type": "conflict",
                    "code": "idempotency_key_reused",
                    "message": "This Idempotency-Key was already used with a different request.",
                    "request_id": "req_4b5c6d7e8f9a0b22"
                  }
                }
              },
              "notCancelable": {
                "summary": "Batch already finished",
                "value": {
                  "error": {
                    "type": "conflict",
                    "code": "batch_not_cancelable",
                    "message": "A completed batch cannot be canceled.",
                    "request_id": "req_4b5c6d7e8f9a0b23"
                  }
                }
              }
            }
          }
        }
      },
      "PayloadTooLarge": {
        "description": "The body exceeds 2 MB (JSON) or 10 MB (CSV).",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "tooLarge": {
                "summary": "CSV over 10 MB",
                "value": {
                  "error": {
                    "type": "invalid_request",
                    "code": "payload_too_large",
                    "message": "The file exceeds 10 MB. Split it into several batches.",
                    "request_id": "req_4b5c6d7e8f9a0b24"
                  }
                }
              }
            }
          }
        }
      },
      "UnsupportedMediaType": {
        "description": "Use `application/json` or, for CSV batches, `multipart/form-data`.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "unsupported": {
                "summary": "Wrong Content-Type",
                "value": {
                  "error": {
                    "type": "invalid_request",
                    "code": "unsupported_media_type",
                    "message": "Use Content-Type application/json.",
                    "request_id": "req_4b5c6d7e8f9a0b25"
                  }
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit or concurrent batch limit exceeded.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          },
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimit-Limit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimit-Remaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimit-Reset"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "rateLimited": {
                "summary": "Too many requests",
                "value": {
                  "error": {
                    "type": "rate_limit",
                    "code": "rate_limit_exceeded",
                    "message": "Too many requests. Retry in 12 seconds.",
                    "request_id": "req_4b5c6d7e8f9a0b26"
                  }
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected error on our side. Safe to retry with the same `Idempotency-Key`.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "internal": {
                "summary": "Internal error",
                "value": {
                  "error": {
                    "type": "api_error",
                    "code": "internal_error",
                    "message": "Something went wrong on our side.",
                    "request_id": "req_4b5c6d7e8f9a0b27"
                  }
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The verification engine is unavailable or the check timed out. Nothing was charged.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/X-Request-Id"
          },
          "Retry-After": {
            "$ref": "#/components/headers/Retry-After"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "timeout": {
                "summary": "Mailbox check did not finish in time",
                "value": {
                  "error": {
                    "type": "api_error",
                    "code": "verification_timeout",
                    "message": "The verification did not finish in time. Nothing was charged.",
                    "request_id": "req_4b5c6d7e8f9a0b28"
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Mode": {
        "type": "string",
        "enum": [
          "basic",
          "mailbox"
        ],
        "description": "`basic`: syntax, domain lists and DNS (1 basic credit). `mailbox`: adds\nthe SMTP mailbox probe (1 mailbox credit, charged only when the verdict\nis not `unknown`).\n"
      },
      "Verdict": {
        "type": "string",
        "enum": [
          "valid",
          "invalid",
          "risky",
          "unknown"
        ]
      },
      "ReasonCode": {
        "type": "string",
        "description": "Stable reason for the verdict. New values may be added.\n\n| Code | Verdict | Mode | Meaning |\n| --- | --- | --- | --- |\n| `syntax_invalid` | invalid | both | Not a valid address in the supported ASCII profile. |\n| `address_unsupported` | unknown | both | Internationalised (non-ASCII) address; not checked. |\n| `domain_not_found` | invalid | both | The domain does not exist (NXDOMAIN). |\n| `domain_null_mx` | invalid | both | The domain declares it accepts no mail (null MX, RFC 7505). |\n| `domain_no_mail_host` | invalid | both | No MX and no A/AAAA record. |\n| `dns_temporary` | unknown | both | DNS failed temporarily. Not charged. |\n| `mailbox_not_checked` | unknown | basic | Domain can receive mail; mailbox not probed. |\n| `disposable_domain` | risky | both | Domain is on the disposable list. |\n| `legacy_domain` | risky | both | Domain of a discontinued provider. |\n| `mailbox_exists` | valid | mailbox | Recipient accepted, random control rejected. |\n| `mailbox_not_found` | invalid | mailbox | Server says the recipient does not exist. |\n| `mailbox_disabled` | risky | mailbox | Server says the mailbox is disabled. |\n| `mailbox_full` | risky | mailbox | Server says the mailbox is full. |\n| `mailbox_forwarded` | risky | mailbox | Server announces forwarding (251). |\n| `provider_directory_rejected` | risky | mailbox | Provider directory rejection (Microsoft 365) without confirmation. |\n| `catch_all` | risky | mailbox | Server also accepts a random recipient. |\n| `catch_all_unresolved` | unknown | mailbox | Recipient accepted but the catch-all control was inconclusive. |\n| `rejection_unconfirmed` | unknown | mailbox | Rejected, but a known-good control was rejected too. |\n| `probe_rate_limited` | unknown | mailbox | Our hourly probe quota for that domain or server is exhausted. |\n| `probe_blocked` | unknown | mailbox | The server refuses our probe (IP reputation, reverse DNS or sender policy). |\n| `smtp_temporary` | unknown | mailbox | Temporary rejection or greylisting. |\n| `smtp_unreachable` | unknown | mailbox | No mail server could be reached. |\n| `smtp_tls_failed` | unknown | mailbox | The advertised TLS session could not be verified. |\n| `smtp_rejected` | unknown | mailbox | Ambiguous or policy rejection that does not prove the mailbox is missing. |\n",
        "examples": [
          "mailbox_exists"
        ]
      },
      "Check": {
        "type": "object",
        "description": "One step that was actually executed, in order. Steps that did not run\nare absent (for example `smtp` in `basic` mode, or `dns` after a syntax\nfailure).\n\n| `name` | `status` values |\n| --- | --- |\n| `syntax` | `ok`, `invalid`, `unsupported` |\n| `disposable`, `legacy`, `free` | `matched` (listed only when the domain matches) |\n| `dns` | `mx`, `implicit_mx`, `nxdomain`, `null_mx`, `no_mail_host`, `temporary` |\n| `smtp` | `accepted`, `missing`, `provider_missing`, `disabled`, `full`, `forwarded`, `temporary`, `limited`, `unreachable`, `tls_failed`, `rejected` |\n| `catch_all` | same values as `smtp`, for the random control recipient |\n",
        "required": [
          "name",
          "status"
        ],
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "syntax",
              "disposable",
              "legacy",
              "free",
              "dns",
              "smtp",
              "catch_all"
            ]
          },
          "status": {
            "type": "string",
            "description": "Outcome of the step. New values may be added."
          }
        }
      },
      "Flags": {
        "type": "object",
        "required": [
          "disposable",
          "free",
          "catch_all"
        ],
        "properties": {
          "disposable": {
            "type": "boolean",
            "description": "The domain (or a parent domain) is on the disposable-email list."
          },
          "free": {
            "type": "boolean",
            "description": "The domain is a free webmail provider. Informational; does not change the verdict."
          },
          "catch_all": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "`true`: the server also accepted a random recipient. `false`: it\nrejected the random recipient. `null`: not tested (`basic` mode,\nrecipient not accepted) or inconclusive.\n"
          }
        }
      },
      "MxRecord": {
        "type": "object",
        "required": [
          "host",
          "preference"
        ],
        "properties": {
          "host": {
            "type": "string"
          },
          "preference": {
            "type": "integer",
            "minimum": 0,
            "maximum": 65535
          }
        }
      },
      "SmtpEvidence": {
        "type": "object",
        "description": "What the recipient's server answered to `RCPT TO` for this address.",
        "required": [
          "mx",
          "code",
          "enhanced_code",
          "tls"
        ],
        "properties": {
          "mx": {
            "type": [
              "string",
              "null"
            ],
            "description": "Mail server that answered."
          },
          "code": {
            "type": [
              "integer",
              "null"
            ],
            "description": "SMTP reply code, when a reply was received."
          },
          "enhanced_code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Enhanced status code (RFC 3463), when present."
          },
          "tls": {
            "type": "boolean",
            "description": "Whether the session used verified TLS."
          }
        }
      },
      "Verification": {
        "type": "object",
        "required": [
          "id",
          "object",
          "livemode",
          "email",
          "mode",
          "verdict",
          "reason_code",
          "reason",
          "flags",
          "checks",
          "mx",
          "smtp",
          "cached",
          "credits_charged",
          "checked_at",
          "retry_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^ver_[a-f0-9]{32}$"
          },
          "object": {
            "type": "string",
            "enum": [
              "verification"
            ]
          },
          "livemode": {
            "type": "boolean"
          },
          "email": {
            "type": "string",
            "description": "The address as verified, trimmed and lower-cased."
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "verdict": {
            "$ref": "#/components/schemas/Verdict"
          },
          "reason_code": {
            "$ref": "#/components/schemas/ReasonCode"
          },
          "reason": {
            "type": "string",
            "description": "Human-readable explanation of `reason_code`, in the language of `Accept-Language`."
          },
          "flags": {
            "$ref": "#/components/schemas/Flags"
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "mx": {
            "type": "array",
            "description": "Mail servers of the domain, as resolved. Empty when DNS was not resolved.",
            "items": {
              "$ref": "#/components/schemas/MxRecord"
            }
          },
          "smtp": {
            "description": "`null` in `basic` mode or when the probe did not run.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/SmtpEvidence"
              },
              {
                "type": "null"
              }
            ]
          },
          "cached": {
            "type": "boolean",
            "description": "The result was served from a recent check; `checked_at` is the time of that check."
          },
          "credits_charged": {
            "type": "integer",
            "enum": [
              0,
              1
            ],
            "description": "Credits of the type of `mode` charged for this result."
          },
          "checked_at": {
            "type": "string",
            "format": "date-time"
          },
          "retry_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When a temporary result can be verified again. In batches this is handled for you."
          }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "Address to verify. Leading/trailing spaces and case are normalised."
          },
          "mode": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Mode"
              }
            ],
            "default": "basic"
          }
        }
      },
      "BatchCreateRequest": {
        "type": "object",
        "required": [
          "emails"
        ],
        "properties": {
          "emails": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10000,
            "items": {
              "type": "string",
              "maxLength": 1024
            }
          },
          "mode": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Mode"
              }
            ],
            "default": "basic"
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional label shown in the dashboard."
          }
        }
      },
      "BatchCsvUpload": {
        "type": "object",
        "required": [
          "file"
        ],
        "properties": {
          "file": {
            "type": "string",
            "contentMediaType": "text/csv",
            "description": "UTF-8 CSV with a header row. Up to 10 MB and 100,000 data rows."
          },
          "mode": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Mode"
              }
            ],
            "default": "basic"
          },
          "email_column": {
            "type": "string",
            "default": "email",
            "description": "Exact name of the header that holds the addresses."
          },
          "delimiter": {
            "type": "string",
            "enum": [
              "comma",
              "semicolon",
              "tab"
            ],
            "default": "comma"
          },
          "name": {
            "type": "string",
            "maxLength": 120,
            "description": "Optional label shown in the dashboard."
          }
        }
      },
      "BatchStatus": {
        "type": "string",
        "enum": [
          "queued",
          "processing",
          "completed",
          "canceled",
          "failed"
        ],
        "description": "`queued` → `processing` → `completed`. `canceled` after\n`POST /batches/{batch_id}/cancel`. `failed` only for an internal error;\nreserved credits are returned.\n"
      },
      "Batch": {
        "type": "object",
        "required": [
          "id",
          "object",
          "livemode",
          "name",
          "source",
          "mode",
          "status",
          "total",
          "unique",
          "processed",
          "summary",
          "credits",
          "created_at",
          "started_at",
          "finished_at",
          "deadline_at",
          "results_expire_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^bat_[a-f0-9]{32}$"
          },
          "object": {
            "type": "string",
            "enum": [
              "batch"
            ]
          },
          "livemode": {
            "type": "boolean"
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": "string",
            "enum": [
              "json",
              "csv"
            ]
          },
          "mode": {
            "$ref": "#/components/schemas/Mode"
          },
          "status": {
            "$ref": "#/components/schemas/BatchStatus"
          },
          "total": {
            "type": "integer",
            "description": "Rows accepted, including duplicates."
          },
          "unique": {
            "type": "integer",
            "description": "Distinct addresses after normalisation."
          },
          "processed": {
            "type": "integer",
            "description": "Rows with a final result."
          },
          "summary": {
            "type": "object",
            "description": "Final results so far, by verdict (rows, including duplicates).",
            "required": [
              "valid",
              "invalid",
              "risky",
              "unknown"
            ],
            "properties": {
              "valid": {
                "type": "integer"
              },
              "invalid": {
                "type": "integer"
              },
              "risky": {
                "type": "integer"
              },
              "unknown": {
                "type": "integer"
              }
            }
          },
          "credits": {
            "type": "object",
            "required": [
              "type",
              "reserved",
              "charged"
            ],
            "properties": {
              "type": {
                "$ref": "#/components/schemas/Mode"
              },
              "reserved": {
                "type": "integer",
                "description": "Credits still held for rows without a final result."
              },
              "charged": {
                "type": "integer",
                "description": "Credits charged so far."
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the batch reached `completed`, `canceled` or `failed`."
          },
          "deadline_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Processing deadline (6 days after start). Rows unresolved by then end as `unknown`, free of charge."
          },
          "results_expire_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When inputs and results are deleted (30 days after `finished_at`)."
          }
        }
      },
      "BatchList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Batch"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "BatchResult": {
        "allOf": [
          {
            "type": "object",
            "required": [
              "row",
              "input",
              "duplicate"
            ],
            "properties": {
              "row": {
                "type": "integer",
                "minimum": 1,
                "description": "1-based position in `emails`, or data row number in the CSV (header excluded)."
              },
              "input": {
                "type": "string",
                "description": "The value exactly as submitted."
              },
              "duplicate": {
                "type": "boolean",
                "description": "`true` when an earlier row holds the same address; duplicates are never charged."
              }
            }
          },
          {
            "$ref": "#/components/schemas/Verification"
          }
        ]
      },
      "BatchResultList": {
        "type": "object",
        "required": [
          "object",
          "data",
          "has_more",
          "next_cursor"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "list"
            ]
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchResult"
            }
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "object",
          "livemode",
          "credits",
          "period",
          "usage"
        ],
        "properties": {
          "object": {
            "type": "string",
            "enum": [
              "usage"
            ]
          },
          "livemode": {
            "type": "boolean"
          },
          "credits": {
            "type": "object",
            "required": [
              "basic",
              "mailbox"
            ],
            "properties": {
              "basic": {
                "type": "object",
                "required": [
                  "remaining",
                  "reserved",
                  "granted",
                  "resets_at"
                ],
                "properties": {
                  "remaining": {
                    "type": "integer"
                  },
                  "reserved": {
                    "type": "integer",
                    "description": "Held by running batches."
                  },
                  "granted": {
                    "type": "integer",
                    "description": "Monthly allowance of the current period."
                  },
                  "resets_at": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              },
              "mailbox": {
                "type": "object",
                "required": [
                  "remaining",
                  "reserved",
                  "next_expiry"
                ],
                "properties": {
                  "remaining": {
                    "type": "integer"
                  },
                  "reserved": {
                    "type": "integer",
                    "description": "Held by running batches."
                  },
                  "next_expiry": {
                    "description": "The next credits to expire, or `null` when none expire.",
                    "oneOf": [
                      {
                        "type": "object",
                        "required": [
                          "amount",
                          "at"
                        ],
                        "properties": {
                          "amount": {
                            "type": "integer"
                          },
                          "at": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              }
            }
          },
          "period": {
            "type": "object",
            "description": "Current billing period of the basic allowance.",
            "required": [
              "start",
              "end"
            ],
            "properties": {
              "start": {
                "type": "string",
                "format": "date-time"
              },
              "end": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "Activity in the current period.",
            "required": [
              "basic",
              "mailbox"
            ],
            "properties": {
              "basic": {
                "$ref": "#/components/schemas/UsageCounters"
              },
              "mailbox": {
                "$ref": "#/components/schemas/UsageCounters"
              }
            }
          }
        }
      },
      "UsageCounters": {
        "type": "object",
        "required": [
          "verifications",
          "credits_charged"
        ],
        "properties": {
          "verifications": {
            "type": "integer",
            "description": "Verifications completed, single and batch."
          },
          "credits_charged": {
            "type": "integer"
          }
        }
      },
      "Account": {
        "type": "object",
        "required": [
          "id",
          "object",
          "livemode",
          "name",
          "plan",
          "api_key",
          "limits",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^org_[a-f0-9]{16}$"
          },
          "object": {
            "type": "string",
            "enum": [
              "account"
            ]
          },
          "livemode": {
            "type": "boolean",
            "description": "`false` when the request used a `sk_test_…` key."
          },
          "name": {
            "type": "string"
          },
          "plan": {
            "type": "object",
            "required": [
              "id",
              "status"
            ],
            "properties": {
              "id": {
                "type": "string",
                "enum": [
                  "free",
                  "basic",
                  "basic_plus"
                ]
              },
              "status": {
                "type": "string",
                "enum": [
                  "active",
                  "past_due",
                  "canceled"
                ]
              }
            }
          },
          "api_key": {
            "type": "object",
            "description": "The key used for this request. The secret is never returned.",
            "required": [
              "id",
              "name",
              "prefix",
              "created_at"
            ],
            "properties": {
              "id": {
                "type": "string",
                "pattern": "^key_[a-f0-9]{16}$"
              },
              "name": {
                "type": "string"
              },
              "prefix": {
                "type": "string",
                "description": "First characters of the key, as shown in the dashboard."
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              }
            }
          },
          "limits": {
            "type": "object",
            "required": [
              "requests_per_minute",
              "max_batch_size",
              "max_concurrent_batches",
              "modes"
            ],
            "properties": {
              "requests_per_minute": {
                "type": "integer"
              },
              "max_batch_size": {
                "type": "integer",
                "description": "Maximum rows per batch for this plan."
              },
              "max_concurrent_batches": {
                "type": "integer",
                "description": "Batches that may be `queued` or `processing` at once."
              },
              "modes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Mode"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "type",
          "code",
          "message",
          "request_id"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "invalid_request",
              "authentication",
              "payment_required",
              "permission",
              "not_found",
              "conflict",
              "rate_limit",
              "api_error"
            ]
          },
          "code": {
            "type": "string",
            "description": "Stable machine-readable code (see the table in the API description). New values may be added."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation. Do not parse it."
          },
          "param": {
            "type": "string",
            "description": "Request field the error refers to, when there is one."
          },
          "request_id": {
            "type": "string",
            "description": "Same value as the `X-Request-Id` header."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "EventBase": {
        "type": "object",
        "required": [
          "id",
          "object",
          "type",
          "livemode",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^evt_[a-f0-9]{32}$",
            "description": "Unique per event; identical across retries. Use it to deduplicate."
          },
          "object": {
            "type": "string",
            "enum": [
              "event"
            ]
          },
          "type": {
            "type": "string"
          },
          "livemode": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BatchCompletedEvent": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EventBase"
          },
          {
            "type": "object",
            "required": [
              "type",
              "data"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "batch.completed"
                ]
              },
              "data": {
                "type": "object",
                "required": [
                  "batch"
                ],
                "properties": {
                  "batch": {
                    "$ref": "#/components/schemas/Batch"
                  }
                }
              }
            }
          }
        ]
      },
      "CreditsLowEvent": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EventBase"
          },
          {
            "type": "object",
            "required": [
              "type",
              "data"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "credits.low"
                ]
              },
              "data": {
                "type": "object",
                "required": [
                  "credit_type",
                  "remaining",
                  "threshold"
                ],
                "properties": {
                  "credit_type": {
                    "$ref": "#/components/schemas/Mode"
                  },
                  "remaining": {
                    "type": "integer"
                  },
                  "threshold": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}
