openapi: 3.1.2
info:
  title: SendPulse Verifier 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.
  - name: Single Email Verification
    description: Endpoints related to Single Email Verification.
  - name: Reports
    description: Endpoints related to Reports.
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
  /verifier-service/send-single-to-verify:
    post:
      tags:
        - Single Email Verification
      summary: Verify a single email address
      operationId: verifySingleEmail
      description: Send one email address for real-time verification.
      x-ai-role: email_deliverability_expert
      x-ai-description: >
        Enables on-the-fly validation for individual contacts.  Ideal for
        real-time signup forms or manual entry to ensure only valid data enters
        the system.
      x-ai-reasoning-instructions:
        - Verify email syntax before sending.
        - >-
          Advise the user that this only initiates the check; results must be
          fetched separately.
      x-ai-responding-instructions:
        - Confirm the verification task is created.
        - Suggest fetching the result via `getSingleVerificationResult` next.
      x-ai-suggestions:
        - 'email: ''test@example.com'''
      x-ai-capabilities:
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Verification started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultTrue'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/get-single-result:
    get:
      tags:
        - Single Email Verification
      summary: Get email address verification results
      operationId: getSingleVerificationResult
      description: Retrieve the verification result for a single email address.
      x-ai-role: email_deliverability_expert
      x-ai-description: >-
        Provides a detailed breakdown of an individual email's health and
        technical validity.
      x-ai-reasoning-instructions:
        - >-
          Check 'disposable' and 'gibberish' flags to detect bot or temporary
          accounts.
        - >-
          Analyze 'webmail' flag to distinguish personal from corporate
          addresses.
        - >-
          If status is not 1 (Valid), advise the user not to send to this
          address.
      x-ai-responding-instructions:
        - Clearly state if the email is 'Valid' or 'Invalid'.
        - >-
          Highlight specific risks like 'Disposable service detected' if
          applicable.
      x-ai-suggestions:
        - 'email: ''test@example.com'''
      x-ai-capabilities:
        security_info:
          data_handling:
            - InformationRetrieval
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Verification results
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    $ref: '#/components/schemas/SingleEmailResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/make-report:
    post:
      tags:
        - Reports
      summary: Create a mailing list verification report
      operationId: createVerificationReport
      description: Generate a downloadable file with verification results.
      x-ai-role: data_analyst
      x-ai-description: >-
        Exports the audit results into a structured file format for offline
        analysis or external reporting.
      x-ai-reasoning-instructions:
        - >-
          Select an appropriate format (CSV, XLS, XLSX) based on the user's data
          processing needs.
        - >-
          Filter the statuses (e.g., only 'Invalid') if the user wants to focus
          on cleanup.
        - Specify the language for headers if necessary.
      x-ai-responding-instructions:
        - Confirm the report generation has started.
        - Instruct the user to use `viewVerificationReport` once ready.
      x-ai-suggestions:
        - 'format: 4 (XLSX)'
        - 'status: [1,2,3]'
      x-ai-capabilities:
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
                format:
                  type: integer
                  description: 2 — csv, 3 — xls, 4 — xlsx; default is 2
                  enum:
                    - 2
                    - 3
                    - 4
                  default: 2
                status:
                  type: array
                  items:
                    type: integer
                  description: >-
                    Statuses to include: 0 — unverified, 1 — valid, 2 —
                    unconfirmed, 3 — invalid
                  example:
                    - 1
                    - 2
                    - 3
                lang:
                  type: string
                  example: en
      responses:
        '200':
          description: Report creation started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultTrue'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/check-report:
    get:
      tags:
        - Reports
      summary: View a mailing list verification report
      operationId: viewVerificationReport
      description: Get metadata and a sample of the generated report.
      x-ai-role: data_analyst
      x-ai-description: >-
        Provides a preview and verification of the report content before
        download.
      x-ai-reasoning-instructions:
        - Ensure `make-report` was called previously.
        - >-
          Check the 'status' of the mailing list in the report
          (Red/Yellow/Green).
      x-ai-responding-instructions:
        - Show a summary of the report contents (counts of each status).
        - 'Provide the next step: `downloadVerificationReport`.'
      x-ai-suggestions:
        - 'id: 89165888'
      x-ai-capabilities:
        security_info:
          data_handling:
            - InformationRetrieval
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
        - name: format
          in: query
          schema:
            type: integer
            default: 2
      responses:
        '200':
          description: Report details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingListVerificationResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /verifier-service/get-report:
    get:
      tags:
        - Reports
      summary: Download mailing list verification report
      operationId: downloadVerificationReport
      description: >-
        Download the full report file. Note that the report is deleted from the
        server after download.
      x-ai-role: data_analyst
      x-ai-description: >-
        The final retrieval of the cleaning results. This is a one-time download
        for security and storage efficiency.
      x-ai-reasoning-instructions:
        - >-
          Warn the user that this is a single-use link; they must save the file
          locally.
        - Verify the format matches the one used during creation.
      x-ai-responding-instructions:
        - Provide the binary stream or download link.
        - Remind the user that the report is now removed from SendPulse servers.
      x-ai-suggestions:
        - 'id: 89165888'
      x-ai-capabilities:
        security_info:
          data_handling:
            - InformationRetrieval
            - DataDestruction
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
        - name: format
          in: query
          schema:
            type: integer
            default: 2
      responses:
        '200':
          description: Report file download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  schemas:
    ResultTrue:
      type: object
      properties:
        result:
          type: boolean
          example: true
    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
    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
    SingleEmailResult:
      type: object
      properties:
        email:
          type: string
        checks:
          type: object
          properties:
            status:
              type: integer
            valid_format:
              type: integer
            disposable:
              type: integer
            webmail:
              type: integer
            gibberish:
              type: integer
            status_text:
              type: string
  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.
