openapi: 3.0.3
info:
  title: flexEngage Email Validation API
  description:
    >
    Our Email Validation API allows retail system integrators the capability to validate one or many email addresses in real
    time.  We offer two options for email validation - frontend (pre-transaction) or backend (post-transaction).
  contact:
    name: FlexEngage Support
    email: support@flexengage.com
  version: 0.0.1

servers:
- url: 'https://api-test.flexreceipts-lab.com'
  description: Test Environment
- url: 'https://api.flexreceipts.com'
  description: Production Environment

paths:
  /email-validation:
    get:
      parameters:
        - name: emailAddress
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: List of email addresses to validate.
          examples:
            one:
              value: test1@test.com
            multiple:
              value: test1@test.com,test2@test.com,test3@test.com
      responses:
        '200':
          description: |
            Contains status of the email address validation.   Below is a list of email status codes that can be returned in the API response.  Emails that have a status of “valid” or “unknown” are recommended for sending emails.
            - valid - Email address has been verified to be real and currently accepting emails
            - invalid - Email address has been verified to be bad and is not accepting emails
            - unknown - Email address’s status cannot be definitely determined.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationResponse'
              examples:
                invalid:
                    value:
                      "test@test,com": { "status": "invalid" }
                valid:
                    value:
                      "test@test.com": { "status": "valid" }
                unknown:
                    value:
                      "test@test.com": { "status": "unknown" }
        '422':
          description: Error will be returned for validation errors.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        '403':
          description: Unauthorized access
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        '500':
          description: Error will be thrown for internal exceptions.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

components:
  schemas:
    EmailValidation:
      type: object
      properties:
        status:
          type: string
          description: Response status for email address
          enum:
            - valid
            - invalid
            - unknown

    EmailValidationResponse:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/EmailValidation'


    ErrorResponse:
      title: Error Response
      type: object
      additionalProperties: false
      properties:
        message:
          type: string
        code:
          type: string
        referenceId:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ErrorEntry'
    ErrorEntry:
      type: object
      additionalProperties: false
      properties:
        code:
          type: string
        message:
          type: string
  responses: { }
  parameters: { }
  examples: { }
  requestBodies: { }
  headers: { }
  securitySchemes:
    basic:
      description: |
        All requests are secured with basic authentication.  Credentials
        are provided with your account information.
      type: http
      scheme: basic
  links: { }
  callbacks: { }