SendBridge Mail Tester API

openapi: 3.2.0
info:
  title: Sendbridge Mail Tester 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: Mail Tester
  description: Generate a unique inbox, send a message to it, then poll the deliverability report. Live calls charge 200 credits. Test keys return a completed demo report for free.
paths:
  /mailtester/tests:
    post:
      tags:
      - Mail Tester
      operationId: createMailTest
      summary: Create a test address
      description: Allocates `{token}@test.sendbridge.com`. Send a message to that address, then poll `GET /mailtester/tests/{token}`.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailTestRequest'
      responses:
        '201':
          description: Test address created.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MailTestAddress'
                  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'
  /mailtester/get_address:
    post:
      tags:
      - Mail Tester
      operationId: getMailTestAddress
      summary: Create a test address (RPC alias)
      description: Alias of `POST /mailtester/tests`.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailTestRequest'
      responses:
        '201':
          description: Test address created.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MailTestAddress'
                  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'
  /mailtester/tests/{token}:
    get:
      tags:
      - Mail Tester
      operationId: getMailTestResult
      summary: Fetch a test report
      description: '`token` may be the 12-character test token or the full `{token}@test.sendbridge.com` address. Poll until `status` is `completed`.'
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Current status and report when ready.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MailTestResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /mailtester/get_result:
    post:
      tags:
      - Mail Tester
      operationId: getMailTestResultRpc
      summary: Fetch a test report (RPC alias)
      description: Alias of `GET /mailtester/tests/{token}`. Pass `test_token` or `email_address` in the JSON body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMailTestRequest'
      responses:
        '200':
          description: Current status and report when ready.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/MailTestResult'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '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'
    NotFound:
      description: The resource was not found.
      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'
    MailTestAddress:
      type: object
      required:
      - test_token
      - email_address
      - poll_after_seconds
      properties:
        test_token:
          type: string
          examples:
          - abc123def456
        email_address:
          type: string
          examples:
          - abc123def456@test.sendbridge.com
        expires_at:
          type:
          - string
          - 'null'
        poll_after_seconds:
          type: integer
          examples:
          - 5
        reference:
          type:
          - string
          - 'null'
    CreateMailTestRequest:
      type: object
      properties:
        reference:
          type:
          - string
          - 'null'
          description: Optional id on your side. Echoed back, not stored as a lookup key.
    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
    MailTestReport:
      type: object
      description: Deliverability report. Raw email and original headers are never returned.
      properties:
        test_token:
          type: string
        report_id:
          type:
          - string
          - 'null'
        email_from:
          type:
          - string
          - 'null'
        email_subject:
          type:
          - string
          - 'null'
        email_received_at:
          type:
          - string
          - 'null'
        from_domain:
          type:
          - string
          - 'null'
        score:
          type:
          - number
          - 'null'
        grade:
          type:
          - string
          - 'null'
        category_scores:
          type:
          - object
          - 'null'
          additionalProperties: true
        rspamd_score:
          type:
          - number
          - 'null'
        rspamd_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        spamassassin_score:
          type:
          - number
          - 'null'
        spamassassin_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        spf_result:
          type:
          - string
          - 'null'
        spf_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        dkim_result:
          type:
          - string
          - 'null'
        dkim_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        dmarc_result:
          type:
          - string
          - 'null'
        dmarc_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        arc_result:
          type:
          - string
          - 'null'
        arc_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        bimi_result:
          type:
          - string
          - 'null'
        bimi_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        iprev_result:
          type:
          - string
          - 'null'
        iprev_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        alignment_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        headers_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        mime_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        tls_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        helo_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        unsubscribe_details:
          type:
          - object
          - 'null'
          additionalProperties: true
        dns_checks:
          type:
          - object
          - 'null'
          additionalProperties: true
        blacklist_checks:
          type:
          - array
          - object
          - 'null'
        broken_links:
          type:
          - array
          - object
          - 'null'
        content_analysis:
          type:
          - object
          - 'null'
          additionalProperties: true
        sender_ip:
          type:
          - string
          - 'null'
        created_at:
          type:
          - string
          - 'null'
        expires_at:
          type:
          - string
          - 'null'
    MailTestResult:
      type: object
      required:
      - status
      - poll_after_seconds
      - report
      properties:
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
        poll_after_seconds:
          type: integer
        report:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/MailTestReport'
    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
    GetMailTestRequest:
      type: object
      properties:
        test_token:
          type: string
        email_address:
          type: string
          format: email
  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_`.