{
  "openapi": "3.1.0",
  "info": {
    "title": "ZBounce Email Verification API",
    "version": "3.4.0"
  },
  "servers": [
    {
      "url": "https://api.zbounce.net"
    }
  ],
  "paths": {
    "/v1/me": {
      "get": {
        "tags": [
          "Public"
        ],
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "summary": "Get current API key information",
        "description": "Returns comprehensive statistics for the currently authenticated API key, including its type, remaining checks, credit line status (for monthly plans), and expiration details.",
        "responses": {
          "200": {
            "description": "Current API key information",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyResponse"
                },
                "examples": {
                  "monthly_key_example": {
                    "summary": "Example response for a monthly API key with credit line active",
                    "value": {
                      "type": "monthly",
                      "remaining": 100,
                      "reserved": 0,
                      "used": 0,
                      "expires_at": "2023-10-05T14:48:00Z",
                      "monthly_quota": 100,
                      "credit_issued": true,
                      "credit_amount": 100,
                      "credit_due": 100,
                      "credit_start": "2023-09-05T14:48:00Z"
                    }
                  },
                  "pay_as_you_go_example": {
                    "summary": "Example response for a pay-as-you-go API key",
                    "value": {
                      "type": "pay_as_you_go",
                      "remaining": 75,
                      "reserved": 2,
                      "used": 10,
                      "expires_at": "2023-12-15T23:59:59Z",
                      "monthly_quota": 0,
                      "credit_issued": false,
                      "credit_amount": 0,
                      "credit_due": 0,
                      "credit_start": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid API key"
          }
        }
      }
    },
    "/v1/fast-verify": {
      "post": {
        "tags": [
          "Public"
        ],
        "summary": "Fast single-address verification",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FastVerifyRequest"
              },
              "examples": {
                "/v1/fast-verify": {
                  "summary": "One address",
                  "value": {
                    "email": "john.doe@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "403": {
            "description": "Invalid key / exhausted quota"
          },
          "429": {
            "description": "Server busy"
          }
        }
      }
    },
    "/v1/tasks": {
      "post": {
        "tags": [
          "Public"
        ],
        "summary": "Create verification task",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaskRequest"
              },
              "examples": {
                "simple": {
                  "summary": "No webhook",
                  "value": {
                    "emails": [
                      "alice@example.com",
                      "bob@yahoo.com"
                    ]
                  }
                },
                "with_tags": {
                  "summary": "With tags",
                  "value": {
                    "emails": [
                      "user@example.com"
                    ],
                    "tags": [
                      "newsletter",
                      "promo"
                    ]
                  }
                },
                "with_webhook_completed": {
                  "summary": "Webhook on completion",
                  "value": {
                    "emails": [
                      "john@example.com",
                      "jane@example.net"
                    ],
                    "webhook": {
                      "url": "https://myapp.com/hooks/status",
                      "secret": "hmac_secret",
                      "mode": "completed"
                    },
                    "tags": [
                      "newsletter",
                      "weekly"
                    ]
                  }
                },
                "with_webhook_results": {
                  "summary": "Webhook with full results",
                  "value": {
                    "emails": [
                      "a@ex.com",
                      "b@ex.net"
                    ],
                    "webhook": {
                      "url": "https://myapp.com/hooks/results",
                      "mode": "results",
                      "max_retries": 5,
                      "timeout_ms": 8000
                    },
                    "tags": [
                      "newsletter",
                      "weekly"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "403": {
            "description": "Quota exhausted / invalid key"
          }
        }
      }
    },
    "/v1/tasks/{task_id}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Get verification task status",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponse"
                }
              }
            }
          },
          "404": {
            "description": "Task not found"
          }
        }
      }
    },
    "/v1/tasks-results/{task_id}": {
      "get": {
        "tags": [
          "Public"
        ],
        "summary": "Paginated verification results",
        "security": [
          {
            "ApiKeyAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 100,
              "minimum": 1,
              "maximum": 1000
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResults"
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/v1/demo": {
      "post": {
        "tags": [
          "Public"
        ],
        "summary": "Free single-address demo (rate limited)",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FastVerifyRequest"
              },
              "examples": {
                "/v1/fast-verify": {
                  "summary": "One address",
                  "value": {
                    "email": "john.doe@example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailReport"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON"
          },
          "403": {
            "description": "Invalid key / exhausted quota"
          },
          "429": {
            "description": "Server busy"
          }
        },
        "operationId": "demoVerify"
      }
    }
  },
  "tags": [
    {
      "name": "Public",
      "description": "Email verification"
    }
  ],
  "components": {
    "schemas": {
      "BasicAuth": {
        "type": "object",
        "properties": {
          "user": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        }
      },
      "CreateTaskRequest": {
        "type": "object",
        "required": [
          "emails"
        ],
        "properties": {
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            },
            "minItems": 1,
            "maxItems": 10000
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional tags for the verification task"
          },
          "webhook": {
            "$ref": "#/components/schemas/WebhookConfig"
          }
        }
      },
      "EmailReport": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "disposable": {
            "type": "boolean"
          },
          "exists": {
            "type": "boolean"
          },
          "permanent_error": {
            "type": "boolean"
          },
          "error_category": {
            "type": "string"
          },
          "ttl": {
            "type": "integer",
            "description": "Retry-after (seconds) for temporary errors"
          },
          "accept_all": {
            "type": "boolean",
            "description": "True when the domain is catch-all"
          }
        }
      },
      "FastVerifyRequest": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "email": {
            "type": "string",
            "maxLength": 256,
            "pattern": "^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$"
          }
        }
      },
      "KeyResponse": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "monthly",
              "pay_as_you_go"
            ]
          },
          "remaining": {
            "type": "integer",
            "format": "int32"
          },
          "reserved": {
            "type": "integer",
            "format": "int32"
          },
          "used": {
            "type": "integer",
            "format": "int32"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "monthly_quota": {
            "type": "integer",
            "format": "int32"
          },
          "credit_issued": {
            "type": "boolean"
          },
          "credit_amount": {
            "type": "integer",
            "format": "int32"
          },
          "credit_due": {
            "type": "integer",
            "format": "int32"
          },
          "credit_start": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "type",
          "remaining",
          "reserved",
          "used",
          "expires_at"
        ],
        "example": {
          "type": "monthly",
          "remaining": 100,
          "reserved": 0,
          "used": 0,
          "expires_at": "2023-10-05T14:48:00Z",
          "monthly_quota": 100,
          "credit_issued": true,
          "credit_amount": 100,
          "credit_due": 100,
          "credit_start": "2023-09-05T14:48:00Z"
        }
      },
      "KeySummary": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "pay_as_you_go",
              "monthly"
            ]
          },
          "remaining": {
            "type": "integer"
          },
          "reserved": {
            "type": "integer"
          },
          "used": {
            "type": "integer"
          },
          "expires_at": {
            "type": "integer",
            "description": "unix ts"
          }
        }
      },
      "PaginatedResults": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer"
          },
          "total": {
            "type": "integer"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/EmailReport"
            }
          }
        }
      },
      "TaskResponse": {
        "type": "object",
        "properties": {
          "task_id": {
            "type": "string"
          },
          "accepted": {
            "type": "integer"
          },
          "skipped": {
            "type": "integer"
          }
        }
      },
      "TaskStatusResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "total": {
            "type": "integer"
          },
          "done": {
            "type": "integer"
          },
          "total_pages": {
            "type": "integer"
          },
          "created_at": {
            "type": "integer",
            "description": "Unix timestamp"
          },
          "key": {
            "$ref": "#/components/schemas/KeySummary"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Tags associated with the task"
          }
        }
      },
      "WebhookConfig": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "secret": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "completed",
              "results"
            ],
            "default": "completed"
          },
          "max_retries": {
            "type": "integer",
            "minimum": 0,
            "default": 3
          },
          "timeout_ms": {
            "type": "integer",
            "minimum": 1000,
            "default": 5000
          },
          "dlq_url": {
            "type": "string",
            "format": "uri"
          },
          "event_url": {
            "type": "string",
            "description": "Optional URL for subscription events. Receives email tracking events with payload structure:\n{\n  \"task_id\": \"uuid\",\n  \"email\": \"user@example.com\",\n  \"event\": \"open\" | \"unsubscribe\" | \"resubscribe\",\n  \"timestamp\": \"ISO8601\"\n}",
            "example": "https://yourdomain.com/webhook/events"
          },
          "basic_auth": {
            "$ref": "#/components/schemas/BasicAuth"
          }
        }
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}