{
  "openapi": "3.1.0",
  "info": {
    "title": "Verifly Email Verification API",
    "version": "1.1.0",
    "description": "Pay-as-you-go email verification API for developers, SaaS products, signup validation, bulk email list cleaning, CSV workflows, and AI agents. Use Verifly to verify deliverability, clean lists, extract emails from text, detect risky addresses, and inspect usage/credit balance.",
    "contact": {
      "name": "Verifly Team",
      "email": "hello@veriflyemail.com",
      "url": "https://verifly.email/docs"
    },
    "termsOfService": "https://verifly.email/terms"
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://verifly.email/api/v1",
      "description": "Production API"
    }
  ],
  "externalDocs": {
    "description": "Verifly API docs",
    "url": "https://verifly.email/docs"
  },
  "tags": [
    {
      "name": "Verification",
      "description": "Mailbox-level email verification and batch verification."
    },
    {
      "name": "List Cleaning",
      "description": "Email list cleaning and extraction utilities."
    },
    {
      "name": "Account",
      "description": "Read-only credit and usage endpoints."
    },
    {
      "name": "AI Agents",
      "description": "Agent-friendly operations for ChatGPT, Custom GPT Actions, MCP, CLI, and workflow builders."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/verify": {
      "get": {
        "tags": [
          "Verification",
          "AI Agents"
        ],
        "operationId": "verifyEmail",
        "summary": "Verify one email address",
        "description": "Verify a single email address for API-first signup validation, lead-list hygiene, and agent-callable email verification. Costs one credit when the upstream verification result is chargeable; some catch-all or unknown results may be refunded by the API.",
        "parameters": [
          {
            "name": "email",
            "in": "query",
            "required": true,
            "description": "Email address to verify, for example lead@example.com.",
            "schema": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Single email verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                },
                "examples": {
                  "deliverable": {
                    "value": {
                      "email": "lead@example.com",
                      "result": "valid",
                      "quality": "good",
                      "disposable": false,
                      "role": false,
                      "free": false,
                      "credits": {
                        "used": 1,
                        "remaining": 99
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-openai-isConsequential": true
      }
    },
    "/verify/batch": {
      "post": {
        "tags": [
          "Verification",
          "AI Agents"
        ],
        "operationId": "verifyEmailBatch",
        "summary": "Verify up to 100 email addresses",
        "description": "Verify a small email batch for workflow automation, ChatGPT Actions, CSV previews, and CRM import checks. The API deduplicates exact duplicates before charging.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailBatchRequest"
              },
              "examples": {
                "simple": {
                  "value": {
                    "emails": [
                      "lead@example.com",
                      "sales@example.com"
                    ],
                    "options": {
                      "exclude_role_accounts": false,
                      "exclude_public_domains": false
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch verification results and counts.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchVerificationResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "402": {
            "$ref": "#/components/responses/InsufficientCredits"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        },
        "x-openai-isConsequential": true
      }
    },
    "/clean": {
      "post": {
        "tags": [
          "List Cleaning",
          "AI Agents"
        ],
        "operationId": "cleanEmailList",
        "summary": "Clean and filter an email list",
        "description": "Clean an email list without mailbox verification. Removes duplicates, invalid formats, optional public-domain emails, optional role accounts, optional disposable domains, and custom blacklist matches. Useful before spending credits or importing a CRM/CSV list.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CleanRequest"
              },
              "examples": {
                "list": {
                  "value": {
                    "emails": [
                      "lead@example.com",
                      "lead@example.com",
                      "info@example.com",
                      "bad-email"
                    ],
                    "options": {
                      "exclude_role_accounts": true,
                      "remove_disposable": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cleaned list and removal statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CleanResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-openai-isConsequential": false
      }
    },
    "/extract": {
      "post": {
        "tags": [
          "List Cleaning",
          "AI Agents"
        ],
        "operationId": "extractEmails",
        "summary": "Extract email addresses from text",
        "description": "Extract email addresses from raw text, documents, logs, scraped snippets, or pasted CRM notes before cleaning or verification. This endpoint does not verify mailbox deliverability.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ExtractRequest"
              },
              "examples": {
                "note": {
                  "value": {
                    "text": "Contact jane@example.com and sales@example.com.",
                    "options": {
                      "deduplicate": true,
                      "lowercase": true
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Extracted emails and domain statistics.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ExtractResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-openai-isConsequential": false
      }
    },
    "/credits": {
      "get": {
        "tags": [
          "Account",
          "AI Agents"
        ],
        "operationId": "getCreditBalance",
        "summary": "Get credit balance",
        "description": "Read the authenticated account credit balance and recent usage totals. This read-only endpoint helps agents decide whether a verification workflow can continue.",
        "responses": {
          "200": {
            "description": "Credit balance and usage totals.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditsResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-openai-isConsequential": false
      }
    },
    "/usage": {
      "get": {
        "tags": [
          "Account"
        ],
        "operationId": "getUsageSummary",
        "summary": "Get API usage summary",
        "description": "Read recent API usage for the authenticated account. Useful for dashboards, budget checks, and agent status summaries.",
        "parameters": [
          {
            "name": "period",
            "in": "query",
            "required": false,
            "description": "Usage period to summarize.",
            "schema": {
              "type": "string",
              "enum": [
                "day",
                "week",
                "month"
              ],
              "default": "month"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum recent usage rows to return. Server caps this value at 1000.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage summary with daily and recent rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        },
        "x-openai-isConsequential": false
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "Verifly API key",
        "description": "Use Authorization: Bearer vf_your_api_key. Never expose API keys in prompts, logs, screenshots, client-side code, or public examples."
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Invalid request or invalid email input.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResult"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResult"
            }
          }
        }
      },
      "InsufficientCredits": {
        "description": "Not enough Verifly credits to complete the verification request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResult"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests for the authenticated account.",
        "headers": {
          "X-RateLimit-Limit": {
            "schema": {
              "type": "string"
            }
          },
          "X-RateLimit-Remaining": {
            "schema": {
              "type": "string"
            }
          },
          "X-RateLimit-Reset": {
            "schema": {
              "type": "string"
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResult"
            }
          }
        }
      },
      "ServerError": {
        "description": "Internal verification or server error. Credits are refunded on failed verification exceptions when possible.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResult"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "suggestion": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "success",
          "error"
        ]
      },
      "Credits": {
        "type": "object",
        "properties": {
          "used": {
            "type": "integer",
            "minimum": 0
          },
          "remaining": {
            "type": "integer",
            "minimum": 0
          }
        },
        "required": [
          "used",
          "remaining"
        ]
      },
      "VerificationResult": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "email_original": {
            "type": "string"
          },
          "result": {
            "type": "string",
            "description": "Provider verification result such as valid, invalid, catch_all, unknown, or risky."
          },
          "quality": {
            "type": "string"
          },
          "disposable": {
            "type": "boolean"
          },
          "role": {
            "type": "boolean"
          },
          "free": {
            "type": "boolean"
          },
          "credits": {
            "$ref": "#/components/schemas/Credits"
          }
        }
      },
      "EmailBatchRequest": {
        "type": "object",
        "properties": {
          "emails": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            }
          },
          "options": {
            "type": "object",
            "properties": {
              "deduplicate": {
                "type": "boolean",
                "default": true
              },
              "exclude_public_domains": {
                "type": "boolean",
                "default": false
              },
              "exclude_role_accounts": {
                "type": "boolean",
                "default": false
              },
              "domain_blacklist": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "pattern_blacklist": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "emails"
        ]
      },
      "BatchVerificationResult": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "success": {
            "type": "boolean"
          },
          "total": {
            "type": "integer"
          },
          "verified_count": {
            "type": "integer"
          },
          "skipped_count": {
            "type": "integer"
          },
          "valid_count": {
            "type": "integer"
          },
          "invalid_count": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VerificationResult"
            }
          },
          "skipped": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkippedEmail"
            }
          },
          "credits": {
            "$ref": "#/components/schemas/Credits"
          }
        }
      },
      "CleanRequest": {
        "type": "object",
        "properties": {
          "emails": {
            "type": "array",
            "minItems": 1,
            "maxItems": 10000,
            "items": {
              "type": "string"
            }
          },
          "options": {
            "$ref": "#/components/schemas/CleanOptions"
          },
          "exclude_public_domains": {
            "type": "boolean"
          },
          "remove_public": {
            "type": "boolean"
          },
          "exclude_role_accounts": {
            "type": "boolean"
          },
          "remove_role": {
            "type": "boolean"
          },
          "remove_disposable": {
            "type": "boolean"
          },
          "domain_blacklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pattern_blacklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "emails"
        ]
      },
      "CleanOptions": {
        "type": "object",
        "properties": {
          "exclude_public_domains": {
            "type": "boolean",
            "default": false
          },
          "remove_public": {
            "type": "boolean",
            "default": false
          },
          "exclude_role_accounts": {
            "type": "boolean",
            "default": false
          },
          "remove_role": {
            "type": "boolean",
            "default": false
          },
          "remove_disposable": {
            "type": "boolean",
            "default": false
          },
          "domain_blacklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "pattern_blacklist": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "additionalProperties": false
      },
      "CleanResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "original_count": {
            "type": "integer"
          },
          "cleaned_count": {
            "type": "integer"
          },
          "removed_count": {
            "type": "integer"
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "removed": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SkippedEmail"
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "duplicates": {
                "type": "integer"
              },
              "invalid_format": {
                "type": "integer"
              },
              "public_domains": {
                "type": "integer"
              },
              "role_accounts": {
                "type": "integer"
              },
              "disposable": {
                "type": "integer"
              },
              "blacklisted_domains": {
                "type": "integer"
              },
              "matched_patterns": {
                "type": "integer"
              }
            }
          }
        },
        "required": [
          "success",
          "original_count",
          "cleaned_count",
          "removed_count",
          "emails",
          "removed",
          "stats"
        ]
      },
      "ExtractRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 1000000,
            "description": "Text or CSV content that may contain email addresses."
          },
          "options": {
            "type": "object",
            "properties": {
              "deduplicate": {
                "type": "boolean",
                "default": true
              },
              "lowercase": {
                "type": "boolean",
                "default": true
              }
            },
            "additionalProperties": false
          }
        },
        "required": [
          "text"
        ]
      },
      "ExtractResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "email"
            }
          },
          "stats": {
            "type": "object",
            "properties": {
              "total_matches": {
                "type": "integer"
              },
              "unique_count": {
                "type": "integer"
              },
              "domains_found": {
                "type": "integer"
              },
              "top_domains": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "domain",
                    "count"
                  ]
                }
              }
            }
          }
        },
        "required": [
          "success",
          "count",
          "emails",
          "stats"
        ]
      },
      "CreditsResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "credits": {
            "type": "integer"
          },
          "used_today": {
            "type": "integer"
          },
          "used_this_month": {
            "type": "integer"
          },
          "plan": {
            "type": "string"
          }
        },
        "required": [
          "success",
          "credits",
          "used_today",
          "used_this_month",
          "plan"
        ]
      },
      "UsageResult": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "period": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "start_date": {
            "type": "string",
            "format": "date-time"
          },
          "end_date": {
            "type": "string",
            "format": "date-time"
          },
          "summary": {
            "type": "object",
            "additionalProperties": true
          },
          "daily": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          },
          "recent": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": true
            }
          }
        },
        "required": [
          "success",
          "period",
          "start_date",
          "end_date",
          "summary"
        ]
      },
      "SkippedEmail": {
        "type": "object",
        "properties": {
          "email": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "email",
          "reason"
        ]
      }
    }
  },
  "x-agent-guidance": {
    "useWhen": [
      "email verification API",
      "bulk email list cleaning",
      "signup validation",
      "disposable email detection",
      "ChatGPT email verification action",
      "AI agent email hygiene"
    ],
    "safety": [
      "Do not expose API keys.",
      "Do not invent verification results.",
      "Ask before processing private or large email lists.",
      "Verifly verifies and cleans lists; it does not send outreach emails."
    ],
    "chatgptAction": "https://verifly.email/chatgpt-action-openapi.json",
    "mcp": "https://verifly.email/mcp-email-verification",
    "cli": "https://verifly.email/cli"
  }
}