openapi: 3.2.0
info:
  title: CustomerOS Email Verification API
  description: CustomerOS API for multiple services (Verify, Enrich, Orgs)
  contact: {}
  version: '1.0'
servers:
- url: https://api.customeros.ai/
tags:
- name: Email Verification
paths:
  /verify/v1/email:
    get:
      tags:
      - Email Verification
      summary: Verify single email address
      description: Performs comprehensive validation of a single email address
      parameters:
      - name: address
        in: query
        description: Email address to verify
        required: true
        schema:
          type: string
          format: email
      - name: verifyCatchAll
        in: query
        description: Verify catch-all domain
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: Email verification results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restverify.EmailVerificationResponse'
        '400':
          description: Invalid email format or missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
      security:
      - ApiKeyAuth: []
  /verify/v1/email/bulk:
    post:
      tags:
      - Email Verification
      summary: Upload emails for bulk verification
      description: Initiates bulk verification process for emails from CSV file
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - file
              type: object
              properties:
                file:
                  type: string
                  description: CSV file containing email addresses
                  format: binary
                emailColumn:
                  type: string
                  description: CSV column containing emails
                  default: first column
                verifyCatchAll:
                  type: boolean
                  description: Verify catch-all domains
                  default: true
        required: true
      responses:
        '200':
          description: Bulk verification initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restverify.BulkUploadResponse'
        '400':
          description: Invalid file format or missing parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
      security:
      - ApiKeyAuth: []
  /verify/v1/email/bulk/results/{requestId}:
    get:
      tags:
      - Email Verification
      summary: Get bulk verification results
      description: Retrieves results or status of bulk verification job
      parameters:
      - name: requestId
        in: path
        description: Bulk verification job ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Verification results or status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/restverify.BulkResultsResponse'
        '400':
          description: Invalid job ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '404':
          description: Job not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
      security:
      - ApiKeyAuth: []
  /verify/v1/email/bulk/results/{requestId}/download:
    get:
      tags:
      - Email Verification
      summary: Download bulk verification results
      description: Downloads CSV file containing detailed verification results
      parameters:
      - name: requestId
        in: path
        description: Bulk verification job ID
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: CSV file containing verification results
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid job ID
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid API key
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '404':
          description: Results not found
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
        '500':
          description: Internal server error
          content:
            text/csv:
              schema:
                $ref: '#/components/schemas/rest.ErrorResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    restverify.EmailVerificationRisk:
      type: object
      properties:
        isFirewalled:
          type: boolean
          description: 'Indicates if email is behind a firewall

            required: true'
          example: false
        isFreeProvider:
          type: boolean
          description: 'Indicates if email uses a free provider

            required: true'
          example: true
        isMailboxFull:
          type: boolean
          description: 'Indicates if mailbox is full

            required: true'
          example: false
        isPrimaryDomain:
          type: boolean
          description: 'Indicates if domain is primary

            required: true'
          example: true
        isRoleMailbox:
          type: boolean
          description: 'Indicates if email is a role account

            required: true'
          example: false
        isSystemGenerated:
          type: boolean
          description: 'Indicates if email is system-generated

            required: true'
          example: false
      description: Risk factors associated with the email address
    restverify.EmailVerificationRecord:
      type: object
      properties:
        alternateEmail:
          type: string
          description: 'Alternative email address if available

            required: false

            format: email'
          example: alternate@example.com
        deliverable:
          type: string
          description: 'Deliverability status

            required: true

            enum: true,false,unknown'
          example: 'true'
        emailAddress:
          type: string
          description: 'Email address that was verified

            required: true

            format: email'
          example: example@example.com
        isCatchAll:
          type: boolean
          description: 'Indicates if domain is catch-all

            required: true'
          example: false
        isRisky:
          type: boolean
          description: 'Indicates if email is considered risky

            required: true'
          example: false
        provider:
          type: string
          description: 'Email service provider

            required: false'
          example: gmail
        risk:
          type: object
          description: 'Risk assessment details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationRisk'
        secureGatewayProvider:
          type: string
          description: 'Security gateway provider

            required: false'
          example: Proofpoint
        syntax:
          type: object
          description: 'Syntax validation details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationSyntax'
      description: Detailed validation results for an email address
    rest.ErrorResponse:
      type: object
      properties:
        message:
          type: string
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or "error")
          example: success
    restverify.BulkResultsDetails:
      type: object
      properties:
        deliverable:
          type: integer
          description: 'Number of deliverable emails

            required: true

            minimum: 0'
          example: 950
        downloadUrl:
          type: string
          description: 'URL to download detailed results

            required: true

            format: uri'
          example: https://api.customeros.ai/verify/v1/email/bulk/results/550e8400-e29b-41d4-a716-446655440000/download
        totalEmails:
          type: integer
          description: 'Total number of emails processed

            required: true

            minimum: 0'
          example: 1000
        undeliverable:
          type: integer
          description: 'Number of undeliverable emails

            required: true

            minimum: 0'
          example: 45
      description: Detailed statistics for bulk verification results
    restverify.BulkUploadResponse:
      type: object
      properties:
        estimatedCompletionTs:
          type: number
          description: 'Estimated completion timestamp

            required: true'
          example: 1694030400
        jobId:
          type: string
          description: 'Unique job identifier

            required: true

            format: uuid'
          example: 550e8400-e29b-41d4-a716-446655440000
        message:
          type: string
          description: 'Status message

            required: true'
          example: File uploaded successfully
        resultUrl:
          type: string
          description: 'URL to check verification results

            required: true

            format: uri'
          example: https://api.customeros.ai/verify/v1/email/bulk/results/550e8400-e29b-41d4-a716-446655440000
      description: Response after initiating bulk email verification
    restverify.EmailVerificationSyntax:
      type: object
      properties:
        domain:
          type: string
          description: 'Domain part of email

            required: true'
          example: example.com
        isValid:
          type: boolean
          description: 'Indicates if email syntax is valid

            required: true'
          example: true
        user:
          type: string
          description: 'Local part of email

            required: true'
          example: example
      description: Email syntax validation details
    restverify.EmailVerificationResponse:
      type: object
      properties:
        email:
          type: object
          description: 'Email verification details

            required: true'
          allOf:
          - $ref: '#/components/schemas/restverify.EmailVerificationRecord'
        requestId:
          type: string
          example: 1234567890abcdef
        status:
          type: string
          description: Status indicates the result of the operation ("success" or "error")
          example: success
      description: Response for single email verification including detailed validation results
    restverify.BulkResultsResponse:
      type: object
      properties:
        estimatedCompletionTs:
          type: integer
          description: 'Estimated completion timestamp

            required: true'
          example: 1694030400
        fileName:
          type: string
          description: 'Original filename

            required: true'
          example: emails.csv
        jobId:
          type: string
          description: 'Unique job identifier

            required: true

            format: uuid'
          example: 550e8400-e29b-41d4-a716-446655440000
        message:
          type: string
          description: 'Progress message

            required: true'
          example: Completed 1000 of 1000 emails
        results:
          type: object
          description: 'Verification results if completed

            required: false'
          allOf:
          - $ref: '#/components/schemas/restverify.BulkResultsDetails'
        status:
          type: string
          description: 'Processing status

            required: true

            enum: processing,completed'
          example: completed
      description: Response containing bulk verification results or status
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-CUSTOMER-OS-API-KEY
      in: header
x-original-swagger-version: '2.0'