{
  "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\nand 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": "Bulk Validations",
      "description": "This API provides functionality to upload and manage bulk validation lists and previews.",
      "x-displayName": "Bulk Validations"
    },
    {
      "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": "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": {
        "tags": [
          "Bulk Validations"
        ],
        "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 name for the bulk job must be unique.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "csv file": {
              "schema": {
                "$ref": "#/components/schemas/POST-v4-address-validate-bulk-list_id-csv-file-RequestBody"
              }
            }
          },
          "required": true
        },
        "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"
                }
              }
            }
          }
        },
        "security": [
          {
            "basicAuth": []
          }
        ]
      },
      "get": {
        "tags": [
          "Bulk Validations"
        ],
        "summary": "Get Job V4",
        "description": "Gets a selected job by list ID.",
        "operationId": "api.InitV4API.(*ApiHelpers).isFreeOrFishy.func2-9",
        "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.(*ApiHelpers).isFreeOrFishy.func1-8",
        "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.(*ApiHelpers).isFreeOrFishy.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.(*ApiHelpers).isFreeOrFishy.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.(*ApiHelpers).isFreeOrFishy.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.(*ApiHelpers).isFreeOrFishy.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.(*ApiHelpers).isFreeOrFishy.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": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/github.com-mailgun-validations-validation-AddressParts"
              },
              {
                "type": "null"
              }
            ]
          },
          "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",
            "description": "Response message"
          }
        },
        "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",
              "null"
            ],
            "format": "int32"
          },
          "current": {
            "type": [
              "integer",
              "null"
            ],
            "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"
        ]
      },
      "POST-v4-address-validate-bulk-list_id-csv-file-RequestBody": {
        "type": "object",
        "properties": {
          "": {
            "type": "object",
            "description": "a CSV file, with header row, of emails to validate; the \"email\" column must be present"
          }
        },
        "required": [
          ""
        ]
      },
      "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": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/github.com-mailgun-validations-validation-engagement-EngagementData"
              },
              {
                "type": "null"
              }
            ]
          },
          "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"
                  },
                  "accept_all": {
                    "type": "integer",
                    "format": "int32"
                  }
                },
                "required": [
                  "catch_all",
                  "deliverable",
                  "do_not_send",
                  "undeliverable",
                  "unknown",
                  "accept_all"
                ]
              },
              "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"
      ]
    }
  ]
}