openapi: 3.0.1
info:
  title: OxiBounce API
  description: This API allows you to interact with your OxiBounce services.<br/><br/>To access it, you must first request your identification information by contacting our support team or directly in the OxiBounce app.<br/><b>Authentication</b>
    is done by base64 encoding 'API_USER:API_PASSWORD' and passing it through a <a
    href='https://en.wikipedia.org/wiki/Basic_access_authentication' target='_blank'>basic
    authorization header</a>.<br/>Use the 'Authorize' button below and run any query
    to get details.
    <br/><br/>💡 You will find PHP libraries on our <a href='https://github.com/oxemis/' target='_blank'>Github account</a>.
  contact:
    email: support@oxemis.com
  version: 2.1.0
externalDocs:
  description: Visit the OxiBounce website
  url: https://www.oxibounce.com
servers:
  - url: https://api.oxibounce.com/
tags:
  - name: user
    description: Everything about your OxiBounce account.
  - name: list
    description: Upload a list of emails to check and get results.
  - name: check
    description: Check an email via OxiBounce and get result (unit check).
paths:
  /user:
    get:
      tags:
        - user
      summary: Get information about your OxiBounce account.
      description: This path returns various information about your OxiBounce account.
      responses:
        200:
          description: successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      security:
        - api_key: [ ]
  /list:
    get:
      tags:
        - list
      summary: Get information about your uploaded lists.
      description: This path returns various information about your emails lists.
      responses:
        200:
          description: successful operation.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
        204:
          description: No lists found.
      security:
        - api_key: [ ]
    post:
      tags:
        - list
      summary: Upload a list of emails to check.
      description: This path allows you to upload a list of emails in JSON or CSV format for analysis. JSON files must contain an array of objects with an email property. CSV files must contain a header row including an email column.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The JSON or CSV file to upload. When using JSON, the file content must be an array matching the ListUpload schema.
              required:
                - file
      responses:
        200:
          description: List uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        400:
          description: Invalid file format or other error.
      security:
        - api_key: [ ]
  /list/{id}:
    get:
      tags:
        - list
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the list.
          schema:
            type: integer
            example: 123456
      summary: Get informations about a list of emails.
      description: Get informations about a list of emails.
      responses:
        200:
          description: successful operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        404:
          description: List not found.
      security:
        - api_key: [ ]
    delete:
      tags:
        - list
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the list you want to delete.
          schema:
            type: integer
            example: 123456
      summary: Delete a list of emails.
      description: This path allows you to delete a list of emails.
      responses:
        200:
          description: successful operation.
        404:
          description: List not found.
      security:
        - api_key: [ ]
  /list/{id}/start:
    post:
      tags:
        - list
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the list you want to start.
          schema:
            type: integer
            example: 123456
        - name: adv
          in: query
          required: false
          description: Run an advanced analysis using greylisting. Use 1 to enable it; the default is 0.
          schema:
            type: integer
            enum:
              - 0
              - 1
            default: 0
            example: 0
      summary: Start the analysis of an email list.
      description: This path starts the analysis of an email list. The list status must be "WAITING".
      responses:
        200:
          description: successful operation.
        404:
          description: List not found.
      security:
        - api_key: [ ]
  /list/{id}/stop:
    post:
      tags:
        - list
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the list you want to stop.
          schema:
            type: integer
            example: 123456
      summary: Stop the analysis of an email list.
      description: This path stops the analysis of an email list.
      responses:
        200:
          description: successful operation.
        404:
          description: List not found.
      security:
        - api_key: [ ]
  /list/{id}/results:
    get:
      tags:
        - list
      parameters:
        - name: id
          in: path
          required: true
          description: ID of the list.
          schema:
            type: integer
            example: 123456
        - name: filter
          in: query
          required: false
          description: Filter the results by their status. Possible values are "OK", "KO", or "NOTSURE".
          schema:
            type: string
            enum:
              - OK
              - KO
              - NOTSURE
      summary: Get the results for an email list.
      description: This path allows you to get the results of the analysis. The status of the list MUST be "done" before you call it.
      responses:
        200:
          description: JSON file with the results, returned as an attachment named results.json.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Test'
        404:
          description: List not found.
      security:
        - api_key: [ ]
  /check:
    post:
      tags:
        - check
      summary: Send an email you want to check.
      description: 'Use this path to send the email you want to test. You can send multiples emails like this email1@example.com;email2@example.com... Important : please note if you want to test many emails, we recommend you to use the list upload feature (more efficient).'
      parameters:
        - name: email
          in: query
          required: true
          description: Email you want to test
          schema:
            type: string
            example: email1@example.com;email2@example.com
        - name: adv
          in: query
          required: false
          description: Run an advanced analysis using greylisting. Use 1 to enable it; the default is 0.
          schema:
            type: integer
            enum:
              - 0
              - 1
            example: 0
            default: 0
      responses:
        400:
          description: Invalid query.
        200:
          description: List of tests IDs (you will need these IDs to check the result of the tests)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                    - ID
                    - Email
                  properties:
                    ID:
                      description: Test ID (required to retrieve the result).
                      type: integer
                      example: 19211
                    Email:
                      description: Email address associated with the test ID.
                      type: string
                      format: email
                      example: email1@example.com
      security:
        - api_key: [ ]
    get:
      tags:
        - check
      summary: Get test result using test ID.
      description: Use this path to get the results of the analysis of your emails. Pass the test IDs in the id parameter. Check the Status property to determine whether a test is "PENDING" or "DONE".
      parameters:
        - name: id
          in: query
          required: true
          description: Test IDs for which you want the results, separated by ";". Maximum 100 IDs.
          schema:
            type: string
            example: "19211;19212"
      responses:
        400:
          description: Invalid query.
        200:
          description: List of test results. When Status is "PENDING", Result and ResultDetails are omitted.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Test'
      security:
        - api_key: [ ]
components:
  schemas:
    User:
      type: object
      properties:
        Email:
          type: string
          description: Account email address.
        Credits:
          type: integer
          description: Number of remaining credits.
        CreditsValidBefore:
          type: string
          description: Date until which the credits are valid.
          example: "2024-12-31"
    List:
      type: object
      properties:
        Name:
          type: string
          description: List name.
          example: "My list"
        ID:
          type: integer
          description: List ID.
          example: 19211
        Status:
          type: string
          description: List status :<br/>"WAITING" - waiting for a start command<br/>"PENDING" - analysis is running<br/>"DONE" - analysis is done<br/>"CANCELED" - canceled by user and a stop command<br/>"IMPORTING" - list is loading<br/>"ERROR" - an error occured while importing (no email found in the list for example)
          example: "PENDING"
        CreatedAt:
          type: string
          description: List creation date.
          example: "2021-01-01 12:00:00"
        StartedAt:
          type: string
          description: List processing start date.
          example: "2021-01-01 12:00:00"
        EndedAt:
          type: string
          description: List processing end date.
          example: "2021-01-01 12:00:00"
        NbEmails:
          type: integer
          description: Number of emails in the list.
          example: 100
        NbEmails_Empty:
          type: integer
          description: Number of empty emails.
          example: 10
        NbEmails_Duplicate:
          type: integer
          description: Number of duplicate emails.
          example: 5
        NbEmails_InvalidFormat:
          type: integer
          description: Number of emails with invalid format.
          example: 3
        TotalCost:
          type: integer
          description: Total cost of the list processing.
          example: 10
    ListUpload:
      type: array
      description: JSON file content accepted by POST /list. Each object represents one email to check. Additional columns are accepted and imported with the email.
      items:
        type: object
        required:
          - email
        properties:
          name:
            type: string
            description: Optional contact name.
            example: Alice
          email:
            type: string
            format: email
            description: Email address to check.
            example: alice0@example.com
        additionalProperties: true
      example:
        - name: Alice
          email: alice0@example.com
        - name: Bob
          email: bob1@example.com
    Test:
      type: object
      required:
        - ID
        - Email
        - Status
      properties:
        ID:
          description: Test ID.
          type: integer
          example: 19211
        Email:
          description: Email address associated with the test ID.
          type: string
          example: "email1@example.com"
        Status:
          type: string
          description: Test status ("PENDING" or "DONE")
          enum:
            - PENDING
            - DONE
          example: "DONE"
        Result:
          type: string
          description: "Test result. Possible values :<br/><ul><li>OK : email is valid.</li><li>KO : email is invalid.</li><li>NOT_SURE : it's impossible to tell if the email is valid or not.</li></ul>"
          enum:
            - OK
            - KO
            - NOT_SURE
          example: "KO"
        ResultDetails:
          type: object
          description: Present only when Status is DONE.
          properties:
            Domain:
              type: string
              description: Email domain name
              example: "example.com"
            IsDisposable:
              type: boolean
              description: "Indicates that the address is a disposable address. Disposable addresses can be dangerous because they are not necessarily associated with a single recipient (it is sometimes enough to know the address to consult its contents). Never send messages containing confidential information to such addresses"
              example: false
            IsFormatValid:
              type: boolean
              description: "Indicates whether the address format is valid or not."
              example: true
            IsFreemail:
              type: boolean
              description: "Indicates that the address is a “free” address, therefore not associated with a particular company."
              example: true
            IsRisky:
              type: boolean
              description: "Indicates that the address or its domain is identified as potentially dangerous. It is strongly recommended not to send to these addresses to preserve your reputation."
              example: true
            IsRobot:
              type: boolean
              description: "Indicates that the e-mail address appears to be associated with a robot and not with a real person or a department of a company. Behind some of these addresses are hidden spamtraps. So be very careful."
              example: true
            IsRole:
              type: boolean
              description: "Indicates that the address is that of a department of a company or that it is a generic address (type contact@…)."
              example: true
            MailSystem:
              type: string
              description: "Contains, if identified, the email system used by the owner of the email address."
              example: "microsoft"
            Reason:
              type: string
              description: "The detailed reason for the result."
              example: "ERR_DOESNOTEXIST"
            Suggestion:
              type: string
              description: "In the case of an invalid address, OxiBounce will be able to suggest a correction (gmial.com at the link of gmail.com for example). To be used with caution and manual validation of course."
  securitySchemes:
    api_key:
      type: http
      description: Use your API Login Password to authenticate your queries.<br/>You can create or manage you api keys in the OxiBounce application.
      scheme: basic