openapi: 3.2.0
info:
  title: SendPulse Verifier Mailing List Verification API
  version: 1.0.0
  description: API for email address verification and mailing list cleaning.
  x-ai-description: 'The Verifier API is a critical tool for maintaining high deliverability and protecting sender reputation.  It performs deep validation of email addresses to identify invalid, disposable, or high-risk contacts before they are used in campaigns.

    '
  license:
    name: Apache 2.0
    identifier: Apache-2.0
servers:
- url: https://api.sendpulse.com
  description: Production server
security:
- apiKey: []
- oauth2: []
tags:
- name: Mailing List Verification
  description: Endpoints related to Mailing List Verification.
paths:
  /verifier-service/send-list-to-verify:
    post:
      tags:
      - Mailing List Verification
      summary: Verify mailing list
      operationId: verifyMailingList
      description: Send a mailing list for verification.
      x-ai-role: email_deliverability_expert
      x-ai-description: 'Initiates a comprehensive audit of an entire address book.  This is a strategic step taken before launching a campaign to a new or stale list to prevent hard bounces and protect the sender''s domain reputation.

        '
      x-ai-reasoning-instructions:
      - Ensure that the mailing list has not been used in a campaign yet, as the system restricts verification of active lists.
      - Check if there are any ongoing verifications for the same list ID; concurrent verifications are prohibited.
      - Verify that the account has sufficient verification credits and that the current plan is active.
      - Advise the user that new addresses must be added to the list if they are re-verifying a previously checked book.
      x-ai-responding-instructions:
      - Confirm that the verification process has started successfully.
      - Instruct the user to use the `getVerificationProgress` method to monitor the status.
      - Remind the user that the list cannot be used for sending until the verification is complete.
      x-ai-suggestions:
      - Check progress in 5 minutes.
      x-ai-capabilities:
        security_info:
          data_handling:
          - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: integer
                  description: Mailing list ID to be verified
                  example: 89165888
      responses:
        '200':
          description: Verification started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultTrue'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/get-progress:
    get:
      tags:
      - Mailing List Verification
      summary: Get mailing list verification progress
      operationId: getVerificationProgress
      description: Check the progress of an ongoing mailing list verification.
      x-ai-role: email_deliverability_expert
      x-ai-description: Provides real-time visibility into the batch validation process.
      x-ai-reasoning-instructions:
      - Use this method to poll for status before attempting to fetch final results.
      - Calculate the percentage of completion from 'total' and 'processed' fields.
      - If 'processed' equals 'total', inform the user that results are now available.
      x-ai-responding-instructions:
      - State the current progress (e.g., '80% complete').
      - Predict an estimated time remaining if the processing rate is consistent.
      x-ai-suggestions:
      - 'id: 89165888'
      x-ai-capabilities:
        security_info:
          data_handling:
          - InformationRetrieval
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: integer
        description: Mailing list ID that is being verified
      responses:
        '200':
          description: Verification progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      total:
                        type: integer
                      processed:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/check:
    get:
      tags:
      - Mailing List Verification
      summary: Get mailing list verification results
      operationId: getVerificationResults
      description: Retrieve a list of email addresses with their verification statuses.
      x-ai-role: data_analyst
      x-ai-description: 'Exports the detailed findings of a list audit.  This data allows for granular segmentation based on address health (Valid, Unconfirmed, Invalid).

        '
      x-ai-reasoning-instructions:
      - Must be called after `verifyMailingList` has finished.
      - Apply pagination using 'start' and 'count' for large lists.
      - Analyze the 'status_text' and 'status' codes to advise on list hygiene.
      x-ai-responding-instructions:
      - Summarize the overall health of the list (e.g., 'Green', 'Yellow', 'Red').
      - Highlight the number of valid addresses ready for campaigns.
      - Advise removing 'Invalid' (status 3) addresses immediately.
      x-ai-suggestions:
      - 'start: 0'
      - 'count: 100'
      x-ai-capabilities:
        security_info:
          data_handling:
          - InformationRetrieval
          - PIIDisplay
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: integer
      - name: start
        in: query
        schema:
          type: integer
          default: 0
      - name: count
        in: query
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Verification results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingListVerificationResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/check-list:
    get:
      tags:
      - Mailing List Verification
      summary: Get a list of verified mailing lists
      operationId: getVerifiedLists
      description: Retrieve a summary of all mailing lists that have been verified.
      x-ai-role: data_analyst
      x-ai-description: Provides an audit log of all historical list verification activities.
      x-ai-reasoning-instructions:
      - Use this to identify which lists have been cleaned and which are pending.
      - Monitor 'is_updated' to find lists where new, unverified addresses were added post-check.
      - Check 'is_garbage_in_book' to identify lists with previously known bad data.
      x-ai-responding-instructions:
      - Present a table of verified lists with their last check date and status.
      - Flag lists that need re-verification due to new updates.
      x-ai-suggestions:
      - 'limit: 10'
      x-ai-capabilities:
        security_info:
          data_handling:
          - InformationRetrieval
      parameters:
      - name: start
        in: query
        schema:
          type: integer
          default: 0
      - name: count
        in: query
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: List of verified mailing lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/VerifiedListSummary'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    ResultTrue:
      type: object
      properties:
        result:
          type: boolean
          example: true
    EmailAddressVerification:
      type: object
      properties:
        id:
          type: integer
        email_address:
          type: string
        check_date:
          type: string
        status:
          type: integer
        status_text:
          type: string
    VerifiedListSummary:
      type: object
      properties:
        id:
          type: integer
        address_book_name:
          type: string
        all_emails_quantity:
          type: integer
        status:
          type: integer
        check_date:
          type: string
        data:
          type: object
        is_updated:
          type: integer
        status_text:
          type: string
        is_garbage_in_book:
          type: boolean
    MailingListVerificationResult:
      type: object
      x-ai-description: Detailed breakdown of mailing list health.
      properties:
        id:
          type: integer
        address_book_name:
          type: string
        all_emails_quantity:
          type: integer
        status:
          type: integer
          description: 1 - Green, 2 - Yellow, 3 - Red
        check_date:
          type: string
        data:
          type: object
          properties:
            '0':
              type: integer
              description: Unverified
            '1':
              type: integer
              description: Valid
            '2':
              type: integer
              description: Unconfirmed
            '3':
              type: integer
              description: Invalid
        is_updated:
          type: integer
        status_text:
          type: string
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddressVerification'
        email_addresses_total:
          type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Static API Key authentication.  A long-lived token generated manually in the SendPulse account settings.

        '
      x-ai-description: 'Permanent authentication token. Ideal for simple integrations without token refresh logic.

        '
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: 'Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides temporary tokens (valid for 1 hour) for enhanced security.

        '