{
  "openapi": "3.0.4",
  "info": {
    "title": "Mailerio API",
    "description": "\r\n## Welcome to the Mailerio API\r\n\r\n- **Base URL:** https://api.mailerio.com\r\n- **Authentication:** Use your API key in the `api_key` query or `X-Api-Key` in header.\r\n- **Rate Limiting:** \r\n    - `/validate`: 5 requests/second per API key.\r\n    - `/validatelist`: 25 requests/second per API key.\r\n    - `/account`: 5 requests/second per API key.\r\n- **Business/Enterprise**\r\n    `Contact support@mailerio.com to increase limits.\r\n",
    "version": "v1"
  },
  "paths": {
    "/v{version}/account": {
      "get": {
        "tags": [
          "Account"
        ],
        "summary": "Get account email and balance",
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountDetailsApiBOL"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/validate": {
      "get": {
        "tags": [
          "Validate"
        ],
        "summary": "Validate a single email",
        "description": "##### **Test email addresses without spending credits**\r\n\r\n| Email Address                | Result             |\r\n|------------------------------|------------------------------------|\r\n| deliverable@mailerio.com     | Status = `deliverable`             |\r\n| undeliverable@mailerio.com   | Status = `undeliverable`           |\r\n| risky@mailerio.com           | Status = `risky`                   |\r\n| unknown@mailerio.com         | Status = `unknown`                 |\r\n| role@mailerio.com            | `role = true`                      |\r\n| free@mailerio.com            | `free = true`                      |\r\n| acceptall@mailerio.com       | `acceptall = true`                 |\r\n| disposable@mailerio.com      | `disposable = true`                |\r\n\r\nFeel free to use any of the above addresses for testing without consuming your credits.\r\n            ",
        "parameters": [
          {
            "name": "Email",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Whitelist",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Blacklist",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Rfc",
            "in": "query",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "Level",
            "in": "query",
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResultApiBOL"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/validatelist": {
      "post": {
        "tags": [
          "Validate"
        ],
        "summary": "Validate list of emails.",
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListValidationRequestApiBOL"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ListValidationRequestApiBOL"
              }
            },
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ListValidationRequestApiBOL"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListValidationResponseApiBOL"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/list/{id}/status": {
      "get": {
        "tags": [
          "Validate"
        ],
        "summary": "Get status of the list",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationListStatusBOL"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/list/{id}": {
      "get": {
        "tags": [
          "Validate"
        ],
        "summary": "Get detailed information about the list",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationListApiBOL"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/list/{id}/download": {
      "get": {
        "tags": [
          "Validate"
        ],
        "summary": "Download validated emails list",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "api_key",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AccountDetailsApiBOL": {
        "title": "AccountDetails",
        "required": [
          "email"
        ],
        "type": "object",
        "properties": {
          "email": {
            "type": "string",
            "nullable": true
          },
          "balance": {
            "type": "number",
            "format": "double"
          },
          "rateLimitSingle": {
            "type": "integer",
            "format": "int32"
          },
          "rateLimitList": {
            "type": "integer",
            "format": "int32"
          },
          "rateLimitAccount": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "ListValidationRequestApiBOL": {
        "title": "ListValidationRequest",
        "type": "object",
        "properties": {
          "emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "whitelist": {
            "type": "boolean"
          },
          "blacklist": {
            "type": "boolean"
          },
          "rfc": {
            "type": "boolean"
          },
          "level": {
            "type": "integer",
            "format": "int32"
          },
          "callbackUrl": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ListValidationResponseApiBOL": {
        "title": "ListValidationResponse",
        "required": [
          "status"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ValidationListApiBOL": {
        "title": "ListValidationDetails",
        "required": [
          "name",
          "status"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "started": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completed": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "downloadUrl": {
            "type": "string",
            "nullable": true
          },
          "size": {
            "type": "integer",
            "format": "int32"
          },
          "acceptAll": {
            "type": "integer",
            "format": "int32"
          },
          "disposable": {
            "type": "integer",
            "format": "int32"
          },
          "duration": {
            "type": "number",
            "format": "double"
          },
          "free": {
            "type": "integer",
            "format": "int32"
          },
          "mailboxFull": {
            "type": "integer",
            "format": "int32"
          },
          "noReply": {
            "type": "integer",
            "format": "int32"
          },
          "valid": {
            "type": "integer",
            "format": "int32"
          },
          "role": {
            "type": "integer",
            "format": "int32"
          },
          "averageScore": {
            "type": "integer",
            "format": "int32"
          },
          "deliverable": {
            "type": "integer",
            "format": "int32"
          },
          "undeliverable": {
            "type": "integer",
            "format": "int32"
          },
          "risky": {
            "type": "integer",
            "format": "int32"
          },
          "unknown": {
            "type": "integer",
            "format": "int32"
          },
          "blacklisted": {
            "type": "integer",
            "format": "int32"
          },
          "whitelisted": {
            "type": "integer",
            "format": "int32"
          },
          "greylisted": {
            "type": "integer",
            "format": "int32"
          },
          "duplicate": {
            "type": "integer",
            "format": "int32"
          },
          "tag": {
            "type": "integer",
            "format": "int32"
          },
          "progress": {
            "type": "integer",
            "format": "int32"
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      },
      "ValidationListStatusBOL": {
        "title": "ListValidationStatus",
        "required": [
          "reason",
          "status"
        ],
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "progress": {
            "type": "integer",
            "format": "int32"
          }
        },
        "additionalProperties": false
      },
      "ValidationResultApiBOL": {
        "title": "ValidationResult",
        "required": [
          "email",
          "reason",
          "status"
        ],
        "type": "object",
        "properties": {
          "created": {
            "type": "string",
            "format": "date-time"
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "user": {
            "type": "string",
            "nullable": true
          },
          "domain": {
            "type": "string",
            "nullable": true
          },
          "acceptAll": {
            "type": "boolean",
            "nullable": true
          },
          "disposable": {
            "type": "boolean",
            "nullable": true
          },
          "duration": {
            "type": "number",
            "format": "double"
          },
          "free": {
            "type": "boolean",
            "nullable": true
          },
          "mailboxFull": {
            "type": "boolean",
            "nullable": true
          },
          "mxRecord": {
            "type": "string",
            "nullable": true
          },
          "noReply": {
            "type": "boolean",
            "nullable": true
          },
          "role": {
            "type": "boolean",
            "nullable": true
          },
          "score": {
            "type": "integer",
            "format": "int32",
            "nullable": true
          },
          "smtpProvider": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "nullable": true
          },
          "reason": {
            "type": "string",
            "nullable": true
          },
          "isValid": {
            "type": "boolean"
          },
          "tag": {
            "type": "string",
            "nullable": true
          },
          "validationLevel": {
            "type": "integer",
            "format": "int32"
          },
          "creditsUsed": {
            "type": "number",
            "format": "double"
          }
        },
        "additionalProperties": false
      }
    },
    "securitySchemes": {
      "X-Api-Key": {
        "type": "apiKey",
        "description": "API Key needed to access the endpoints. Use the 'X-Api-Key' header.",
        "name": "X-Api-Key",
        "in": "header"
      },
      "api_key": {
        "type": "apiKey",
        "description": "API Key needed to access the endpoints. Use the 'api_key' query parameter.",
        "name": "api_key",
        "in": "query"
      }
    }
  },
  "security": [
    {
      "X-Api-Key": [ ],
      "api_key": [ ]
    }
  ]
}