{
 "openapi": "3.1.0",
 "info": {
  "title": "Mailercloud Email Verifier API",
  "version": "1.0.0",
  "description": "Verify email addresses programmatically \u2014 single/batch real-time verification and bulk file verification. Credit-based: each billable verification consumes one credit. Create API keys at [app.mailercloud.com/email-verifier/api-keys](https://app.mailercloud.com/email-verifier/api-keys)."
 },
 "servers": [
  {
   "url": "https://verify.mailercloud.com"
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Your Email Verifier API key, sent as `Authorization: Bearer YOUR_API_KEY`. Create keys at [app.mailercloud.com/email-verifier/api-keys](https://app.mailercloud.com/email-verifier/api-keys)."
   }
  }
 },
 "tags": [
  {
   "name": "Verification"
  },
  {
   "name": "Bulk Files"
  }
 ],
 "paths": {
  "/verifyEmail": {
   "post": {
    "summary": "Verify Emails",
    "operationId": "verify-emails",
    "tags": [
     "Verification"
    ],
    "description": "Verify a single email or a batch of up to **50** emails in real time. Duplicates are removed automatically. Each billable result consumes one credit; returns `402` when the account has insufficient credits. Credits are consumed for every verification attempt, including `unknown` results. Same credit balance as file uploads; active Marketing subscribers receive 250 free credits monthly.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "email": {
          "type": "string",
          "description": "A single email address to verify."
         },
         "emails": {
          "type": "array",
          "items": {
           "type": "string"
          },
          "maxItems": 50,
          "description": "Up to 50 email addresses. May be combined with `email`."
         }
        }
       },
       "examples": {
        "single": {
         "summary": "Single email",
         "value": {
          "email": "jane@example.com"
         }
        },
        "batch": {
         "summary": "Batch",
         "value": {
          "emails": [
           "jane@example.com",
           "bob@test.org"
          ]
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Verification results.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "results": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "email": {
              "type": "string"
             },
             "status": {
              "type": "string",
              "description": "Verification status, e.g. `deliverable`, `undeliverable`, `risky`, `unknown`, `pending`."
             },
             "status_info": {
              "type": "object",
              "description": "Human-readable status, source, tag, and a suggested correction for likely typos."
             },
             "domain_server": {
              "type": "object",
              "description": "Domain/MX server details for the address."
             },
             "account_info": {
              "type": "object",
              "description": "Mailbox-level attributes."
             },
             "characteristics": {
              "type": "object",
              "description": "Flags such as disposable, role account, free provider, catch-all."
             },
             "is_valid": {
              "type": "boolean",
              "description": "Whether the address is syntactically valid."
             },
             "is_deliverable": {
              "type": "boolean"
             },
             "email_format": {
              "type": "string",
              "enum": [
               "valid",
               "invalid"
              ]
             },
             "risk_level": {
              "type": "string",
              "description": "Risk bucket derived from the delivery score."
             },
             "delivery_score": {
              "type": "integer",
              "description": "0\u2013100 deliverability score."
             }
            }
           }
          },
          "total": {
           "type": "integer"
          },
          "credits_used": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid body, no emails provided, or more than 50 emails."
     },
     "401": {
      "description": "Missing or invalid API key."
     },
     "402": {
      "description": "Insufficient credits."
     },
     "503": {
      "description": "Service busy \u2014 retry."
     }
    }
   }
  },
  "/verifyFile": {
   "post": {
    "summary": "Upload File for Verification",
    "operationId": "upload-verification-file",
    "tags": [
     "Bulk Files"
    ],
    "description": "Upload a file of email addresses for bulk verification. Max **10 MB** and **100,000 emails** per file. Processing is asynchronous \u2014 poll `GET /verifyFileStatus/{file_id}`. (These are the API upload limits; larger files \u2014 up to 100 MB / 1M addresses in CSV/TXT \u2014 can be verified through the in-app List Verification upload.)",
    "requestBody": {
     "required": true,
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "file"
        ],
        "properties": {
         "file": {
          "type": "string",
          "format": "binary",
          "description": "CSV/TXT file of email addresses."
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "File accepted for processing.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "file_id": {
           "type": "string"
          },
          "file_name": {
           "type": "string"
          },
          "records": {
           "type": "integer"
          },
          "duplicate_count": {
           "type": "integer"
          },
          "status": {
           "type": "string",
           "example": "pending"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing `file` field, malformed multipart, or no valid emails found."
     },
     "401": {
      "description": "Missing or invalid API key."
     },
     "413": {
      "description": "File exceeds 10 MB or 100,000 emails."
     },
     "422": {
      "description": "File could not be parsed."
     }
    }
   }
  },
  "/verifyFiles": {
   "post": {
    "summary": "List Verification Files",
    "operationId": "list-verification-files",
    "tags": [
     "Bulk Files"
    ],
    "description": "List your uploaded verification files with pagination and search.",
    "requestBody": {
     "required": false,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "limit": {
          "type": "integer"
         },
         "offset": {
          "type": "integer"
         },
         "search": {
          "type": "string"
         },
         "sort_by": {
          "type": "string"
         },
         "sort_order": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Paginated file list.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "total": {
           "type": "integer"
          },
          "limit": {
           "type": "integer"
          },
          "offset": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid API key."
     }
    }
   }
  },
  "/verifyFileStatus/{file_id}": {
   "get": {
    "summary": "Get File Verification Status",
    "operationId": "get-file-status",
    "tags": [
     "Bulk Files"
    ],
    "parameters": [
     {
      "name": "file_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "description": "Poll the processing status and result summary of an uploaded file.",
    "responses": {
     "200": {
      "description": "File status and result counts.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "file_id": {
           "type": "string"
          },
          "file_name": {
           "type": "string"
          },
          "status": {
           "type": "string"
          },
          "total_records": {
           "type": "integer"
          },
          "created_at": {
           "type": "string",
           "format": "date-time"
          },
          "deliverable": {
           "type": "integer"
          },
          "invalid": {
           "type": "integer"
          },
          "risky": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid API key."
     },
     "404": {
      "description": "File not found."
     }
    }
   }
  },
  "/verifyFile/download/{file_id}": {
   "get": {
    "summary": "Download Verification Results",
    "operationId": "download-verification-results",
    "tags": [
     "Bulk Files"
    ],
    "parameters": [
     {
      "name": "file_id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "description": "Download the verified results file for a completed verification.",
    "responses": {
     "200": {
      "description": "Results file."
     },
     "401": {
      "description": "Missing or invalid API key."
     },
     "404": {
      "description": "File not found or not yet complete."
     }
    }
   }
  }
 }
}