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
    email: mailbox checks stop at `RCPT TO` and never issue `DATA`.

    ## Authentication

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

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

    ## Modes and credits

    | `mode` | What it checks | Credit used | Can return `valid` |
    | --- | --- | --- | --- |
    | `basic` | Syntax, domain lists (disposable, free), DNS/MX | 1 **basic** credit | No |
    | `mailbox` | Everything in `basic` + SMTP `RCPT TO` probe and catch-all control | 1 **mailbox** credit | Yes |

    - `basic` never contacts the mail server, so a deliverable domain yields
      `unknown` (`mailbox_not_checked`) or `risky` (list signal), never `valid`.
    - `basic`: every completed verification costs 1 basic credit, except
      `dns_temporary` results and repeats of the same address within 30 days.
    - `mailbox`: 1 mailbox credit **only when the verdict is not `unknown`**.
      Repeats of the same address within 24 hours and duplicates inside a batch
      are free.
    - The two balances are independent: one never pays for the other.
    - `credits_charged` on every result tells you exactly what was charged.
    - With no credits left the API answers `402 insufficient_credits`.

    ## Verdicts

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

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

    ## Rate limits

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

    ## Idempotency

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

    ## Errors

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

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

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

    ## Webhooks

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

    ## Data retention

    Batch inputs and results are deleted 30 days after the batch finishes.
    Single verifications are not stored in readable form.
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.
        `basic` normally answers in well under a second. `mailbox` talks to the
        recipient's mail server and can take up to 30 seconds; if it cannot
        finish in time the API answers `503 verification_timeout` and charges
        nothing. For more than a few addresses use batches.
      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.

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

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

        `mailbox` batches respect per-domain and per-server probe quotas and
        retry deferred addresses, so large lists concentrated on a few domains
        can take hours or days. Addresses still unresolved at `deadline_at`
        end as `unknown` and are not charged.
      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
        `batch.completed` webhook. `processed` grows as addresses reach a final
        result.
      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
        listed, so pages requested while the batch is `processing` are partial:
        wait for a terminal status for a complete export. Rows never processed
        in a `canceled` batch are omitted.

        With `format=csv` the body is CSV with the header
        `row,input,email,verdict,reason_code,disposable,free,catch_all,credits_charged,checked_at`
        and the next page is given by the `Link` header (`rel="next"`).
        Results are deleted at `results_expire_at`; after that this endpoint
        answers `404`.
      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
                    1,Ana@Example.com,ana@example.com,valid,mailbox_exists,false,false,false,1,2026-11-17T09:50:04Z
                    3,not-an-email,not-an-email,invalid,syntax_invalid,false,false,,1,2026-11-17T09:50:02Z
        '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
        available and charged; credits reserved for the rest are returned.
        Canceling a batch that is already `canceled` returns it unchanged; a
        `completed` or `failed` batch answers `409 batch_not_cancelable`.
      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
        are reported separately in `reserved`. Basic credits are a monthly
        allowance that resets at `resets_at` and does not roll over. Mailbox
        credits come from one-off packs; credits closest to expiring are spent
        first.
      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
        `data.batch.status`). Not sent for batches you cancel. Fetch the rows
        with `GET /batches/{batch_id}/results`.
      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
        dashboard (default: 10% of the last grant). It is sent again only after
        the balance has been topped up above the threshold and falls below it
        again.
      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
        as `Authorization: Bearer <key>`.
  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
        endpoint secret>`.
      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
        the SMTP mailbox probe (1 mailbox credit, charged only when the verdict
        is not `unknown`).
    Verdict:
      type: string
      enum: [valid, invalid, risky, unknown]
    ReasonCode:
      type: string
      description: |
        Stable reason for the verdict. New values may be added.

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

        | `name` | `status` values |
        | --- | --- |
        | `syntax` | `ok`, `invalid`, `unsupported` |
        | `disposable`, `legacy`, `free` | `matched` (listed only when the domain matches) |
        | `dns` | `mx`, `implicit_mx`, `nxdomain`, `null_mx`, `no_mail_host`, `temporary` |
        | `smtp` | `accepted`, `missing`, `provider_missing`, `disabled`, `full`, `forwarded`, `temporary`, `limited`, `unreachable`, `tls_failed`, `rejected` |
        | `catch_all` | same values as `smtp`, for the random control recipient |
      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
            rejected the random recipient. `null`: not tested (`basic` mode,
            recipient not accepted) or inconclusive.
    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
        `POST /batches/{batch_id}/cancel`. `failed` only for an internal error;
        reserved credits are returned.
    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
