SendBridge Validation API

openapi: 3.2.0
info:
  title: Sendbridge Validation API
  version: 2.0.0
  summary: Email verification and mail testing over a single authenticated API.
  description: 'Sendbridge API v2 is the current public API.


    **Authentication** uses `Authorization: Bearer sbk_live_…` or `sbk_test_…`. Never put the key in the URL.


    **Test keys** (`sbk_test_`) return realistic fixture responses and never charge credits. Start there while you integrate.


    **Live keys** (`sbk_live_`) run the real checks and debit your credit balance.


    Create keys in the app dashboard.


    The previous `/v1/validate` endpoint still works but is frozen. Migrate to `POST /validation/verify`.'
servers:
- url: https://api.sendbridge.com/v2
  description: Production
security:
- bearerAuth: []
tags:
- name: Validation
  description: Verify a single email address. Charges 1 credit on live keys. Test keys return fixtures and are free.
paths:
  /validation/verify:
    post:
      tags:
      - Validation
      operationId: verifyEmail
      summary: Verify an email address
      description: 'Runs syntax, DNS and SMTP checks and returns a deliverability verdict.


        Test-mode shortcuts (the local part of the address):

        - `bounce@…` → `undeliverable`

        - `catchall@…` → `risky`

        - `grey@…` → `unknown` / greylisted

        - anything else → `deliverable`'
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyRequest'
            examples:
              basic:
                value:
                  email: user@example.com
      responses:
        '200':
          description: Verification result.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/VerificationResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    Forbidden:
      description: The API key is missing the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: Not enough credits.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Per-minute rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until the current window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      - meta
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorObject:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - invalid_request
          - unauthorized
          - forbidden_scope
          - not_enough_credits
          - not_found
          - unprocessable
          - rate_limited
          - internal_error
        message:
          type: string
        details:
          type: object
          additionalProperties: true
    VerifyRequest:
      type: object
      required:
      - email
      properties:
        email:
          type: string
          format: email
    Meta:
      type: object
      required:
      - request_id
      properties:
        request_id:
          type: string
          examples:
          - req_9f2c11ab22cd33ef44
        mode:
          type: string
          enum:
          - live
          - test
        credits_charged:
          type: number
        credits_remaining:
          type: number
    VerificationResult:
      type: object
      required:
      - result
      - reason
      - score
      - email
      - syntax
      - domain
      - smtp
      properties:
        result:
          type: string
          enum:
          - deliverable
          - undeliverable
          - risky
          - unknown
        reason:
          type: string
          enum:
          - mailbox_exists
          - invalid_syntax
          - invalid_domain
          - mailbox_not_found
          - catch_all
          - greylisted
          - temporary_failure
          - smtp_unreachable
          - unknown
        score:
          type: integer
          minimum: 0
          maximum: 99
        email:
          type: string
        syntax:
          type: object
          properties:
            valid:
              type: boolean
        domain:
          type: object
          properties:
            mx_found:
              type: boolean
            mx_server:
              type:
              - string
              - 'null'
            free_provider:
              type: boolean
            catch_all:
              type: boolean
        smtp:
          type: object
          properties:
            checked:
              type: boolean
            code:
              type:
              - integer
              - 'null'
            accepts_mail:
              type: boolean
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        maxLength: 255
      description: Optional unique key for POST retries. The original response is replayed for 24 hours.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: API key created in the Sendbridge dashboard. Prefix `sbk_live_` or `sbk_test_`.