openapi: 3.1.0
info:
  title: Validations Service
  description: >-
    Mailgun Email Validation service with RESTful JSON HTTP API for performing
    email validation. This service also manages list

    and CSV ingestion used in bulk validation processing.
  version: 1.0.0
servers:
  - url: https://api.mailgun.net
    description: US Mailgun
  - url: https://api.eu.mailgun.net
    description: EU Mailgun
tags:
  - name: Validations
    description: >-
      This API provides functionality to validate single addresses, and managing
      thresholds.
    x-displayName: Validations
  - name: openapi-validations_other
    x-displayName: other
  - name: List Health Preview
    x-displayName: List Health Preview
  - name: Bulk Validations
    description: >-
      This API provides functionality to upload and manage bulk validation lists
      and previews.
    x-displayName: Bulk Validations
  - name: openapi-bulkvalidations_other
    x-displayName: other
paths:
  /v3/address/validate:
    get:
      summary: Validate Address V3
      description: A single email address to validate.
      operationId: GET-v3-address-validate
      parameters:
        - name: address
          in: query
          description: The address to be validated
          required: true
          schema:
            type: string
        - name: mailbox_verification
          in: query
          description: Enable/disable mailbox verification, default is false
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3Response
              examples:
                Example:
                  value:
                    address: '"Baba Yaga" <john_wick@yaho.com>'
                    did_you_mean: john_wick@yahoo.com
                    mailbox_verification: 'false'
                    parts:
                      display_name: Baba Yaga
                      domain: yaho.com
                      local_part: john_wick
                    reason: No MX records found for domain 'yaho.com'
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
    post:
      summary: Validate Address V3
      description: A single email address to validate.
      operationId: POST-v3-address-validate
      parameters:
        - name: address
          in: query
          description: The address to be validated
          required: true
          schema:
            type: string
        - name: mailbox_verification
          in: query
          description: Enable/disable mailbox verification, default is false
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3Response
              examples:
                Example:
                  value:
                    address: '"Baba Yaga" <john_wick@yaho.com>'
                    did_you_mean: john_wick@yahoo.com
                    mailbox_verification: 'false'
                    parts:
                      display_name: Baba Yaga
                      domain: yaho.com
                      local_part: john_wick
                    reason: No MX records found for domain 'yaho.com'
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v3/address/private/validate:
    get:
      summary: Validate Address V3
      description: A single email address to validate.
      operationId: GET-v3-address-private-validate
      parameters:
        - name: address
          in: query
          description: The address to be validated
          required: true
          schema:
            type: string
        - name: mailbox_verification
          in: query
          description: Enable/disable mailbox verification, default is false
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3Response
              examples:
                Example:
                  value:
                    address: '"Baba Yaga" <john_wick@yaho.com>'
                    did_you_mean: john_wick@yahoo.com
                    mailbox_verification: 'false'
                    parts:
                      display_name: Baba Yaga
                      domain: yaho.com
                      local_part: john_wick
                    reason: No MX records found for domain 'yaho.com'
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
    post:
      summary: Validate Address V3
      description: A single email address to validate.
      operationId: POST-v3-address-private-validate
      parameters:
        - name: address
          in: query
          description: The address to be validated
          required: true
          schema:
            type: string
        - name: mailbox_verification
          in: query
          description: Enable/disable mailbox verification, default is false
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3Response
              examples:
                Example:
                  value:
                    address: '"Baba Yaga" <john_wick@yaho.com>'
                    did_you_mean: john_wick@yahoo.com
                    mailbox_verification: 'false'
                    parts:
                      display_name: Baba Yaga
                      domain: yaho.com
                      local_part: john_wick
                    reason: No MX records found for domain 'yaho.com'
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v3/address/parse:
    get:
      summary: Parse Addresses
      description: >-
        Parses a list of comma separated addresses and optionally perform light
        weight validation of addresses.
      operationId: GET-v3-address-parse
      parameters:
        - name: addresses
          in: query
          description: The comma separated list of addresses
          required: true
          schema:
            type: string
        - name: syntax_only
          in: query
          description: >-
            Enable/disable light weight validation of each address. Default is
            true
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3ParseResponse
              examples:
                Example:
                  value:
                    parsed:
                      - john@wick.com
                      - baba_yaga@wick.com
                    unparseable:
                      - john_wick@yaho.com
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
    post:
      summary: Parse Addresses
      description: >-
        Parses a list of comma separated addresses and optionally perform light
        weight validation of addresses.
      operationId: POST-v3-address-parse
      parameters:
        - name: addresses
          in: query
          description: The comma separated list of addresses
          required: true
          schema:
            type: string
        - name: syntax_only
          in: query
          description: >-
            Enable/disable light weight validation of each address. Default is
            true
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3ParseResponse
              examples:
                Example:
                  value:
                    parsed:
                      - john@wick.com
                      - baba_yaga@wick.com
                    unparseable:
                      - john_wick@yaho.com
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v3/address/private/parse:
    get:
      summary: Parse Addresses
      description: >-
        Parses a list of comma separated addresses and optionally perform light
        weight validation of addresses.
      operationId: GET-v3-address-private-parse
      parameters:
        - name: addresses
          in: query
          description: The comma separated list of addresses
          required: true
          schema:
            type: string
        - name: syntax_only
          in: query
          description: >-
            Enable/disable light weight validation of each address. Default is
            true
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3ParseResponse
              examples:
                Example:
                  value:
                    parsed:
                      - john@wick.com
                      - baba_yaga@wick.com
                    unparseable:
                      - john_wick@yaho.com
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
    post:
      summary: Parse Addresses
      description: >-
        Parses a list of comma separated addresses and optionally perform light
        weight validation of addresses.
      operationId: POST-v3-address-private-parse
      parameters:
        - name: addresses
          in: query
          description: The comma separated list of addresses
          required: true
          schema:
            type: string
        - name: syntax_only
          in: query
          description: >-
            Enable/disable light weight validation of each address. Default is
            true
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-V3ParseResponse
              examples:
                Example:
                  value:
                    parsed:
                      - john@wick.com
                      - baba_yaga@wick.com
                    unparseable:
                      - john_wick@yaho.com
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v3/address/public/threshold:
    get:
      summary: Get Threshold
      description: The validation threshold for this account.
      operationId: GET-v3-address-public-threshold
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-getThresholdResp
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v3/address/platform/threshold:
    get:
      summary: Get Threshold
      description: The validation threshold for this account.
      operationId: GET-v3-address-platform-threshold
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-getThresholdResp
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
  /v4/address/validate/bulk/{list_id}:
    post:
      summary: Create Bulk Job
      description: Validate a full list of addresses.
      operationId: POST-v4-address-validate-bulk--list-id-
      parameters:
        - name: list_id
          in: path
          description: The bulk job list id
          required: true
          schema:
            type: string
      responses:
        '202':
          description: A 202 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-BulkPostResponse
              examples:
                Example:
                  value:
                    id: example_list_id
                    message: The validation job was submitted.
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      tags:
        - openapi-validations_other
      security:
        - basicAuth: []
    get:
      tags:
        - Bulk Validations
      summary: Get Job V4
      description: Gets a selected job by list ID.
      operationId: api.InitV4API
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
              examples:
                Example:
                  value:
                    quantity: 10000
                    id: some-job-name
                    summary:
                      risk:
                        high: 30
                        low: 8000
                        medium: 1010
                        unknown: 460
                      result:
                        donotsend: 30
                        undeliverable: 500
                        unknown: 460
                        catchall: 10
                        deliverable: 9000
                    download_url:
                      csv: https://some-aws-or-gcp-host/file.csv.zip
                      json: https://some-aws-or-gcp-host/file.json.zip
                    status: uploaded
                    created_at: 160000000
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: A 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      security:
        - basicAuth: []
    delete:
      tags:
        - Bulk Validations
      summary: Delete Job V4
      description: Cancels a selected job by list ID.
      operationId: api.InitV4API.
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: Validation job canceled.
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: No validation job processing for list
        '409':
          description: A 409 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: >-
                      The job state is '[bad_state]' and is no longer
                      cancellable
        '500':
          description: A 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: Failed to cancel job, please contact support
      security:
        - basicAuth: []
    options:
      summary: Option V4
      description: Returns a 204; used by mailjet
      operationId: api.NoContentCall-6
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: A 204 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/string'
              examples:
                Example: {}
      tags:
        - openapi-bulkvalidations_other
      security:
        - basicAuth: []
  /v4/address/validate/preview/{list_id}:
    get:
      tags:
        - List Health Preview
      summary: Get List Health Preview Job
      description: A single list health preview job by ID.
      operationId: GET-v4-address-validate-preview--list-id-
      parameters:
        - name: list_id
          in: path
          description: The list health preview id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-models-Preview
              examples:
                Example:
                  value:
                    id: SampleList
                    valid: true
                    status: preview_complete
                    quantity: 1
                    created_at: 1234567890
                    summary:
                      result:
                        deliverable: 100
                        do_not_send: 0
                        undeliverable: 0
                        unknown: 0
                      risk:
                        high: 0
                        low: 100
                        medium: 0
                        unknown: 0
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
    put:
      tags:
        - List Health Preview
      summary: Promote List Health Preview Job
      description: >-
        A currently running list health preview job can be promoted to a full
        bulk validations job, which will validate all addresses in the list.
      operationId: PUT-v4-address-validate-preview--list-id-
      parameters:
        - name: list_id
          in: path
          description: The list health preview job id
          required: true
          schema:
            type: string
      responses:
        '202':
          description: A 202 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-PreviewPostResponse
              examples:
                Example:
                  value:
                    Response:
                      id: example_list_id
                      message: >-
                        The bulk preview job was promoted to a bulk validation
                        job.
                    Status: 202
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
    post:
      tags:
        - List Health Preview
      summary: Create a List Health Preview Job
      description: >-
        Start a list health preview job from a list of addresses. We will sample
        the list and run validations on a small percentage.
      operationId: POST-v4-address-validate-preview--list-id-
      parameters:
        - name: list_id
          in: path
          description: The list health preview job id
          required: true
          schema:
            type: string
      responses:
        '202':
          description: A 202 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-PreviewPostResponse
              examples:
                Example:
                  value:
                    id: example_list_id
                    message: The validation preview was submitted.
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
    delete:
      tags:
        - List Health Preview
      summary: Delete List Health Preview Job
      description: Deletes a single list health previewk job by ID.
      operationId: DELETE-v4-address-validate-preview--list-id-
      parameters:
        - name: list_id
          in: path
          description: The list health preview job id
          required: true
          schema:
            type: string
      responses:
        '202':
          description: A 202 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-PreviewPostResponse
              examples:
                Example:
                  value:
                    id: example_list_id
                    message: The bulk preview was deleted.
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
  /v4/address/validate/preview:
    get:
      tags:
        - List Health Preview
      summary: List List Health Preview Jobs
      description: All list health preview jobs you have started.
      operationId: GET-v4-address-validate-preview
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-api-ListPreviewResponse
              examples:
                Example:
                  value:
                    previews:
                      - id: SampleList
                        valid: true
                        status: preview_complete
                        quantity: 1
                        created_at: 1234567890
                        summary:
                          result:
                            deliverable: 100
                            do_not_send: 0
                            undeliverable: 0
                            unknown: 0
                          risk:
                            high: 0
                            low: 100
                            medium: 0
                            unknown: 0
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
  /v4/address/validate:
    get:
      tags:
        - Validations
      summary: Validate Address V4
      description: A single email address to validate.
      operationId: GET-v4-address-validate
      parameters:
        - name: address
          in: query
          description: The address to be validated
          required: true
          schema:
            type: string
        - name: provider_lookup
          in: query
          description: Enable/disable provider lookup, default is true
          schema:
            type: boolean
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-validations-validation-steps-base-ValidationResponse
              examples:
                Example:
                  value:
                    address: john_snow@yaho.com
                    did_you_mean: john_snow@yahoo.com
                    engagement: {}
                    reason: []
                    result: deliverable
                    risk: low
        default:
          description: A default response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/github.com-mailgun-scaffold-httpapi-GenericResponse
      security:
        - basicAuth: []
  /v4/address/validate/bulk:
    get:
      tags:
        - Bulk Validations
      summary: List Jobs V4
      description: Returns all jobs.
      operationId: api.InitV4API.func4-11
      parameters:
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
              examples:
                Example:
                  value:
                    total: 2
                    jobs:
                      - created_at: 160000001
                        id: some-job-name
                        quantity: 10000
                        records_processed: 3202
                        status: processing
                      - created_at: 160000000
                        download_url:
                          csv: https://some-aws-or-gcp-host/file.csv.zip
                          json: https://some-aws-or-gcp-host/file.json.zip
                        id: some-job-name
                        quantity: 10000
                        status: uploaded
                        summary:
                          engagement: null
                          result:
                            catchall: 10
                            deliverable: 9000
                            donotsend: 30
                            undeliverable: 500
                            unknown: 460
                          risk:
                            high: 30
                            low: 8000
                            medium: 1010
                            unknown: 460
                    paging:
                      prev: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=prev&pivot=
                      first: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=first&pivot=
                      last: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=last&pivot=
                      next: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=next&pivot=
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: A 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      security:
        - basicAuth: []
    options:
      summary: Options V4
      description: Returns a 204; used by mailjet
      operationId: api.NoContentCall-7
      parameters:
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: A 204 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/string'
              examples:
                Example: {}
      tags:
        - openapi-bulkvalidations_other
      security:
        - basicAuth: []
  /v4/address/validate/jobs:
    get:
      summary: List Bulk and Preview V4 Jobs
      description: Returns all jobs.
      operationId: api.InitV4API.func3-10
      parameters:
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
              examples:
                Example:
                  value:
                    jobs:
                      - created_at: 160000000
                        download_url:
                          csv: https://some-aws-or-gcp-host/file.csv.zip
                          json: https://some-aws-or-gcp-host/file.json.zip
                        id: some-list@ninomail.com
                        is_preview: false
                        quantity: 10000
                        status: uploaded
                        summary:
                          engagement: null
                          result:
                            catchall: 10
                            deliverable: 9000
                            donotsend: 30
                            undeliverable: 500
                            unknown: 460
                          risk:
                            high: 30
                            low: 8000
                            medium: 1010
                            unknown: 460
                    paging:
                      last: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=last&pivot=
                      next: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=next&pivot=
                      prev: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=prev&pivot=
                      first: >-
                        http://localhost/v4/address/validate/bulk?limit=10&page=first&pivot=
                    total: 2
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      tags:
        - openapi-bulkvalidations_other
      security:
        - basicAuth: []
  /v3/lists/{list_id}/validate:
    get:
      tags:
        - Bulk Validations
      summary: Get Job V3
      description: Gets a selected job by list ID.
      operationId: api.InitV3API.func2-13
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
              examples:
                Example:
                  value:
                    created_at: 160000000
                    id: some-list@ninomail.com
                    download_url:
                      csv: https://some-aws-or-gcp-host/file.csv.zip
                      json: https://some-aws-or-gcp-host/file.json.zip
                    quantity: 10000
                    status: uploaded
                    summary:
                      result:
                        catchall: 10
                        deliverable: 9000
                        donotsend: 30
                        undeliverable: 500
                        unknown: 460
                      risk:
                        high: 30
                        low: 8000
                        medium: 1010
                        unknown: 460
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: A 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      security:
        - basicAuth: []
    post:
      tags:
        - Bulk Validations
      summary: Create Job V3
      description: Starts a V3 list validation job.
      operationId: api.InitV3API.func3-14
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: The validation job was submitted.
        '400':
          description: A 400 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: Validation job is already active.
      security:
        - basicAuth: []
    delete:
      tags:
        - Bulk Validations
      summary: Delete Job V3
      description: Cancels a selected job by list ID.
      operationId: api.InitV3API.func1-12
      parameters:
        - name: list_id
          in: path
          description: The list ID being verified
          required: true
          schema:
            type: string
        - name: X-Mailgun-Account-Id
          in: header
          description: Mailgun Account ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: Validation job canceled.
        '404':
          description: A 404 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: No validation job processing for list
        '409':
          description: A 409 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: >-
                      The job state is '[bad_state]' and is no longer
                      cancellable
        '500':
          description: A 500 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                Example:
                  value:
                    message: Failed to cancel job, please contact support
      security:
        - basicAuth: []
components:
  schemas:
    github.com-mailgun-validations-validation-AddressParts:
      type: object
      properties:
        display_name:
          type: object
        domain:
          type: object
        local_part:
          type: object
      required:
        - display_name
        - domain
        - local_part
    github.com-mailgun-validations-validation-V3Response:
      type: object
      properties:
        address:
          type: string
        did_you_mean:
          type: object
        is_disposable_address:
          type: boolean
        is_role_address:
          type: boolean
        is_valid:
          type: boolean
        mailbox_verification:
          type: string
        parts:
          $ref: >-
            #/components/schemas/github.com-mailgun-validations-validation-AddressParts
        reason:
          type: object
      required:
        - address
        - did_you_mean
        - is_disposable_address
        - is_role_address
        - is_valid
        - mailbox_verification
        - parts
        - reason
    github.com-mailgun-scaffold-httpapi-GenericResponse:
      type: object
      properties:
        message:
          type: string
      required:
        - message
    github.com-mailgun-validations-validation-V3ParseResponse:
      type: object
      properties:
        parsed:
          type: array
          items:
            type: string
        unparseable:
          type: array
          items:
            type: string
      required:
        - parsed
        - unparseable
    github.com-mailgun-validations-api-getThresholdResp:
      type: object
      properties:
        threshold:
          type: integer
          format: int32
        current:
          type: integer
          format: int32
        triggered:
          type: boolean
      required:
        - threshold
        - current
        - triggered
    github.com-mailgun-validations-api-BulkPostResponse:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
      required:
        - id
        - message
    github.com-mailgun-validations-api-PreviewPostResponse:
      type: object
      properties:
        id:
          type: string
        message:
          type: string
      required:
        - id
        - message
    github.com-mailgun-validations-models-Preview:
      type: object
      properties:
        id:
          type: string
        valid:
          type: boolean
        status:
          type: string
        quantity:
          type: integer
          format: int32
        created_at:
          type: integer
          format: int64
        summary:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: number
              format: float
        reason:
          type: string
      required:
        - id
        - valid
        - status
        - quantity
        - created_at
    github.com-mailgun-validations-api-ListPreviewResponse:
      type: object
      properties:
        previews:
          type: array
          items:
            $ref: '#/components/schemas/github.com-mailgun-validations-models-Preview'
      required:
        - previews
    github.com-mailgun-validations-validation-engagement-EngagementData:
      type: object
      properties:
        engaging:
          type: boolean
        behavior:
          type: string
        is_bot:
          type: boolean
      required:
        - engaging
        - is_bot
    github.com-mailgun-validations-validation-steps-base-ValidationResponse:
      type: object
      properties:
        address:
          type: string
        did_you_mean:
          type: string
        engagement:
          $ref: >-
            #/components/schemas/github.com-mailgun-validations-validation-engagement-EngagementData
        is_disposable_address:
          type: boolean
        is_role_address:
          type: boolean
        reason:
          type: array
          items:
            type: string
        result:
          type: string
        risk:
          type: string
        root_address:
          type: string
        last_seen:
          type: integer
          format: int32
      required:
        - address
        - is_disposable_address
        - is_role_address
        - reason
        - result
        - risk
    string:
      type: string
    Response:
      type: object
      additionalProperties:
        type: object
    GetResponse:
      type: object
      properties:
        is_preview:
          type: boolean
        created_at:
          type: integer
          format: int32
        download_url:
          type: object
          properties:
            json:
              type: string
            csv:
              type: string
          required:
            - csv
            - json
        id:
          type: string
        quantity:
          type: integer
          format: int32
        records_processed:
          type: integer
          format: int32
        status:
          type: string
        summary:
          type: object
          properties:
            engagement:
              type: object
              properties:
                no_data:
                  type: integer
                  format: int32
                highly_engaged:
                  type: integer
                  format: int32
                engaged:
                  type: integer
                  format: int32
                bot:
                  type: integer
                  format: int32
                complainer:
                  type: integer
                  format: int32
                disengaged:
                  type: integer
                  format: int32
              required:
                - highly_engaged
                - engaged
                - bot
                - complainer
                - disengaged
                - no_data
            result:
              type: object
              properties:
                unknown:
                  type: integer
                  format: int32
                catch_all:
                  type: integer
                  format: int32
                deliverable:
                  type: integer
                  format: int32
                do_not_send:
                  type: integer
                  format: int32
                undeliverable:
                  type: integer
                  format: int32
              required:
                - catch_all
                - deliverable
                - do_not_send
                - undeliverable
                - unknown
            risk:
              type: object
              properties:
                unknown:
                  type: integer
                  format: int32
                high:
                  type: integer
                  format: int32
                low:
                  type: integer
                  format: int32
                medium:
                  type: integer
                  format: int32
              required:
                - high
                - low
                - medium
                - unknown
        reason:
          type: string
      required:
        - created_at
        - id
        - quantity
        - records_processed
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic auth using api:YOUR_API_KEY. See
        [documentation](https://documentation.mailgun.com/docs/mailgun/api-reference/authentication/)
x-tagGroups:
  - name: Mailgun Validate
    tags:
      - Validations
      - Bulk Validations
      - List Health Preview
