openapi: 3.0.0
info:
  title: API Reference
  description: ''
  contact:
    name: API Support
    email: hello@truelist.io
  version: 0.2.2

servers:
  - url: https://api.truelist.io

tags:
  - name: Me
    description: Everything about the user that is using the api
  - name: Single email validation
    description: Endpoints used to validate a single email address.  Validation occurs within the request cycle.
  - name: Batch email validation
    description: A Batch is a collection of email addresses that are uploaded to be validated.  Batches are processed in the background and can be checked on later.
  - name: Retrieving results
    description: Endpoints used to retrieve the results of a batch validation.

components:
  schemas:
    error:
      type: object
      properties:
        error:
          type: string
          description: Gives information about what went wrong with the request.
    api_key:
      type: object
      properties:
        active:
          type: boolean
          description: Whether the api token is active or not
        name:
          type: string
          description: The name of the api token
        last_used_at:
          type: string
          format: date-time
          description: The last time the api key was used
        created_at:
          type: string
          format: date-time
          description: When the API key was created

    me:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address of the user
        name:
          type: string
          description: The full name of the user
        uuid:
          type: string
          format: uuid
          description: A unique identifier for the user
        errors:
          type: array
          items:
            type: string
        last_login_at:
          type: string
          description: The last login date of the user
          format: date-time
        time_zone:
          type: string
          description: The time zone for the user
        token:
          type: string
          description: The api token currently in use for the request
        api_keys:
          type: array
          items:
            $ref: '#/components/schemas/api_key'

    email_addresses:
      type: object
      properties:
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/email'

    verify_inline:
      type: object
      properties:
        emails:
          type: array
          items:
            $ref: '#/components/schemas/email'

    email:
      type: object
      properties:
        address:
          type: string
          format: email
          description: The email address
        domain:
          type: string
          description: The email address domain
        canonical:
          type: string
          description: The canonical (or local) part of the email address
        mx_record:
          type: string
          description: The the mx record that was found and used for validation
        email_state:
          type: string
          enum:
            - ok
            - email_invalid
            - risky
            - unknown
            - accept_all
          description: A simple state that shows the verification result.
        email_sub_state:
          type: string
          enum:
            - email_ok
            - accept_all
            - is_disposable
            - is_role
            - failed_mx_check
            - failed_smtp_check
            - failed_spam_trap
            - failed_no_mailbox
            - failed_greylisted
            - failed_syntax_check
            - unknown_error
          description: More details about the email's validation status.
        verified_at:
          type: date-time
          format: email
          example: 2021-01-01T00:00:00Z
          description: The time the email was verified.  If the email already exists in your account and has been validated before, and the email has been checked within your revalidation period, the email will not be revalidated.

    batch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: 'The UUID of the batch'
        batch_state:
          type: string
          enum:
            - pending
            - pending_processing
            - processing
            - completed
          description: The state of the batch verification process
        batch_type:
          type: string
          enum:
            - user_import
              api_import
              integration
          description: Where the batch was created from
        email_count:
          type: integer
          description: The count of emails in the batch.
        processed_count:
          type: integer
          description: The number of emails that have gone through the verification process.
        disposable_count:
          type: integer
          description: The number of disposable emails in the batch.
        role_count:
          type: integer
          description: The number of role emails in the batch.
        failed_syntax_check_count:
          type: integer
          description: The number of email addresses that failed the syntax checker.
        failed_mx_check_count:
          type: integer
          description: The number of email addresses that failed the domain MX check.
        failed_no_mailbox_count:
          type: integer
          description: The number of email addresses do not exist
        ok_for_all_count:
          type: integer
          description: The number of email addresses that have a domain that accepts any email address.
        unknown_count:
          type: integer
          description: The number of email addresses that have an unknown status.
        ok_count:
          type: integer
          description: The number of email addresses are ok for delivery.
        name:
          type: string
          description: The name of the batch.
        webhook_url:
          type: string
          description: Supply a webhook_url when creating a batch.  Truelist will call the url when the batch has completed.
        safest_bet_csv_url:
          type: string
          description: A url to download a csv of the batch with the safest emails.
        highest_reach_csv_url:
          type: string
          description: A url to download a csv of the batch with the highest reach emails.
        only_invalid_csv_url:
          type: string
          description: A url to download a csv of the batch with only invalid emails.
        annotated_csv_url:
          type: string
          description: A url to download a csv of the batch with an extra column that has the email validation results.

  securitySchemes:
    truelist_auth:
      type: apiKey
      in: header
      name: Authorization
      description: The user's bearer token sent via an Authorization header

paths:
  /api/v1/verify_inline:
    post:
      tags:
        - Single email validation
      summary: Verify a single email address
      description:
        "Verify up to 3 email addresses.  Verification will happen inline during the api request. \n

        Validation is bounded by the `timeout` parameter, which defaults to 30 seconds
        and applies to each address separately. When the budget is spent the address is
        returned with `email_state: unknown` and `email_sub_state: timed_out`, and is
        not billed.
        "
      security:
        - truelist_auth: []
      parameters:
        - name: email
          in: query
          required: true
          description: A space-separated list of emails
          examples:
            one:
              summary: A space-separated list of emails
              value: bob@example.com jon@example.com test@example.com
          schema:
            type: string
            format: email
        - name: validation_strategy
          in: query
          required: false
          description: 'The validation strategy to use. Defaults to `accurate`. `fast` skips retry logic for speed. `thorough` waits longer for greylisted servers (5 min retry delay). `enhanced` adds post-validation heuristics for maximum accuracy.'
          schema:
            type: string
            enum:
              - accurate
              - fast
              - thorough
              - enhanced
            default: accurate
        - name: checks
          in: query
          required: false
          description: 'An array of specific checks to run. When provided (without `smtp`), only the requested checks execute, skipping the slower SMTP validation. This is useful for low-latency use cases like signup flows where you want fast feedback (< 200ms) and can defer SMTP verification to a later async call. Valid values: `syntax`, `mx`, `disposable`, `role`, `smtp`. If omitted, all checks run (including SMTP).'
          schema:
            type: array
            items:
              type: string
              enum:
                - syntax
                - mx
                - disposable
                - role
                - smtp
          examples:
            fast_checks:
              summary: Run only fast checks (no SMTP)
              value: ['syntax', 'mx', 'disposable', 'role']
            all_checks:
              summary: Run all checks including SMTP
              value: ['syntax', 'mx', 'disposable', 'role', 'smtp']
        - name: timeout
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 30
          description: >
            Seconds to wait for each address before giving up. Applies per address, so a
            request with 3 addresses may take up to 3 x timeout. Addresses that exceed the
            budget return `email_state: unknown` with `email_sub_state: timed_out` and are
            not billed.
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/verify_inline'
        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '408':
          description: Request timed out - communication with the SMTP server took too long.  Your code logic should handle this error and retry the request later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: Rate limit exceeded - you've hit the rate limit for this endpoint.  Your rate limit is dctated by your plan.  Please wait a bit and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'

  /api/v1/batches:
    post:
      tags:
        - Batch email validation
      summary: Verify a list of emails
      description:
        "Upload a list of emails to verify.  You can either of the following (but not both):\n
        - A `data` parameter that represents a json array of email data.  Should be in the format of `[['email@email.com'], ['email2@email.com']]`.  Each row can also contain arbitrary data, which is useful for supplying external ids or other identifying information.  This data will be returned in the annotated csv result files.  However, one element in the row array must be an email address.  Needs at least 2 rows of data to be valid.\n
        - A binary file upload via the `file` parameter documented below.\n

        Note that batches are processed in the background.  To check on the status of a list, you have a couple of options:\n
        - Poll the status of your batch's progress by `GET`ing the batch you created by its uuid.\n
        - Supply a `webhook_url` when creating the batch.  Truelist will makd a POST request to the url you supplied when the batch is completed.  When we call your url, we'll supply the `batch_id` in the body of the request.

        Also note that counts are not updated until the batch is completed.
        "
      security:
        - truelist_auth: []
      requestBody:
        required: true
        description: this is the description
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The CSV / XLSX file to upload
                uuid:
                  type: string
                  format: uuid
                  description: Supply a UUID if you want the batch to have this UUID.  Otherwise, a random UUID will be generated.
                webhook_url:
                  type: string
                  description: Supply a webhook_url when creating a batch.  Truelist will call the url when the batch has completed.
                validation_strategy:
                  type: string
                  enum:
                    - accurate
                    - fast
                  description: The validation strategy to use for the batch.  Defaults to `accurate`.  Using `fast` will skip our internal backoff/retry logic and deeper validation strategy checks.  This is useful for when you want to validate a large number of emails quickly, but it may result in more false positives.
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                data:
                  type: object
                  description: JSON object of email data.  Should be in the format of `[['email@email.com'], ['email2@email.com']]`.  Each row can contain arbitrary data which will be returned in the annotated csv result file, but one element in the row array must be an email address. Needs at least 2 rows of data to be valid.
                filename:
                  type: string
                  description: The name of the json file.  It will be used as the batch name, as well as the basis for the annotated, safest bet, highest reach, and only invalid csv files.
                uuid:
                  type: string
                  format: uuid
                  description: Supply a UUID if you want the batch to have this UUID.  Otherwise, a random UUID will be generated.
                webhook_url:
                  type: string
                  description: Supply a webhook_url when creating a batch.  Truelist will call the url when the batch has completed.
                validation_strategy:
                  type: string
                  enum:
                    - accurate
                    - fast
                  description: The validation strategy to use for the batch.  Defaults to `accurate`.  Using `fast` will skip our internal backoff/retry logic and deeper validation strategy checks.  This is useful for when you want to validate a large number of emails quickly, but it may result in more false positives.

      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'
        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    get:
      tags:
        - Batch email validation
      summary: Retrieve all batches for your account.
      security:
        - truelist_auth: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/batch'
        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'

  /api/v1/batches/{uuid}:
    get:
      tags:
        - Batch email validation
      summary: Retrieve a single batch by its UUID.
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the batch to get
          schema:
            type: string
            format: uuid
      security:
        - truelist_auth: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'

        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Batch could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    delete:
      tags:
        - Batch email validation
      summary: Delete a batch by its UUID.
      parameters:
        - name: uuid
          in: path
          required: true
          description: The UUID of the batch to get
          schema:
            type: string
            format: uuid
      security:
        - truelist_auth: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/batch'

        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Batch could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: Batch could not be deleted - only completed batches can be deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'

  /me:
    get:
      tags:
        - Me
      summary: Get information about the logged in user
      description: Shows all information about the currently logged in user.
      security:
        - truelist_auth: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/me'

        '401':
          description: User could not be found via token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Gives information about what went wrong with the request.

  /api/v1/email_addresses:
    get:
      tags:
        - Retrieving results
      summary: Retrieve email validation results
      parameters:
        - name: batch_uuid
          in: path
          required: false
          description: The UUID of the batch to get emails from
          schema:
            type: string
            format: uuid
        - name: email_state
          in: path
          required: false
          description: Get emails with a particular email_state
          schema:
            type: string
            enum:
              - ok
              - risky
              - invalid
              - unknown
        - name: email_sub_state
          in: path
          required: false
          description: Get emails with a particular email_sub_state
          schema:
            type: string
            enum:
              - email_ok
              - accept_all
              - is_disposable
              - is_role
              - failed_mx_check
              - failed_smtp_check
              - failed_no_mailbox
              - failed_greylisted
              - failed_syntax_check
        - name: email_address
          in: path
          required: false
          description: Search for a particular email address
          schema:
            type: string
            format: email
        - name: page
          in: path
          required: false
          description: The page number to retrieve.  If not specified, the first page will be returned.
          schema:
            type: integer
        - name: per_page
          in: path
          required: false
          description: The number of emails to return per page.  If not specified, 25 will be returned.  The maximum is 100.
          schema:
            type: integer

      security:
        - truelist_auth: []
      responses:
        '200':
          description: A successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_addresses'

        '401':
          description: User could not be found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'