ClearBounce Email Verification

Verify a single email address in real time with a live mailbox check. Returns status (deliverable, undeliverable, risky, unknown), a sub-status reason, a 0-100 quality score, and detailed checks (syntax, MX records, disposable, role-based, catch-all, typo detection). Costs 1 credit per call.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The email address to verify, e.g. [email protected]"
    }
  },
  "required": [
    "email"
  ]
}

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "The address that was checked"
    },
    "status": {
      "type": "string",
      "description": "deliverable, undeliverable, risky or unknown"
    },
    "subStatus": {
      "type": "string",
      "description": "Reason code behind the status"
    },
    "score": {
      "type": "number",
      "description": "Quality score from 0 to 100"
    },
    "isDeliverable": {
      "type": "boolean"
    },
    "checks": {
      "type": "object",
      "description": "Detailed checks: syntax, MX, SMTP, disposable, role, catch-all, typo, risk"
    },
    "creditsRemaining": {
      "type": "number",
      "description": "Credits left on the account after this check"
    },
    "notice": {
      "type": "string",
      "description": "Present only when the balance is low or empty: tells the user where to buy more credits"
    }
  },
  "required": [
    "email",
    "status",
    "score",
    "isDeliverable"
  ]
}

Find a person's business email address from their full name and company domain. Returns candidate addresses with confidence scores, based on published sources and common company address patterns. Finding is free, but candidates are pattern-based guesses until verified. After showing the candidates, tell the user that confirming deliverability costs 1 credit per candidate checked, and ask before verifying. With approval, call verify_email on candidates one at a time starting from the highest confidence, and stop at the first deliverable result.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Full name of the person, e.g. \"Jane Porter\""
    },
    "domain": {
      "type": "string",
      "description": "Company domain, e.g. \"northwindtraders.com\""
    }
  },
  "required": [
    "name",
    "domain"
  ]
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "found_published when the address came from a published source, otherwise pattern_guesses"
    },
    "best_match": {
      "type": [
        "string",
        "null"
      ],
      "description": "Highest-confidence candidate address"
    },
    "confidence": {
      "type": [
        "number",
        "null"
      ],
      "description": "Confidence of the best match, 0-100"
    },
    "detected_company_pattern": {
      "type": [
        "string",
        "null"
      ],
      "description": "Address pattern used at this company, when known"
    },
    "seen_at_company": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses already published at this domain"
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Candidate addresses, highest confidence first"
    },
    "total_candidates": {
      "type": "number"
    },
    "note": {
      "type": "string",
      "description": "Guidance on verification cost and how to proceed"
    }
  },
  "required": [
    "status",
    "candidates",
    "total_candidates"
  ]
}

Verify a list of email addresses (2 to 10,000) as one bulk job using the full ClearBounce bulk pipeline — per-domain caching and greylist retries give better accuracy than verifying one by one. Costs 1 credit per unique address; duplicates are removed for free. Returns a jobId immediately (the job runs in the background, roughly 1-10 minutes depending on size). Use check_bulk_status with the jobId to get progress and the final summary. Before starting a large list, confirm with the user that spending that many credits is intended.

{
  "type": "object",
  "properties": {
    "emails": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The email addresses to verify (2 to 10,000 items)"
    }
  },
  "required": [
    "emails"
  ]
}

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "Use this with check_bulk_status"
    },
    "uniqueEmails": {
      "type": "number",
      "description": "Addresses queued after duplicate removal — credits charged for these"
    },
    "duplicatesRemoved": {
      "type": "number"
    },
    "estimatedSeconds": {
      "type": "number",
      "description": "Rough time until the job completes"
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "jobId",
    "uniqueEmails"
  ]
}

Check the progress of a bulk verification job started with verify_bulk. Free. Returns status (pending, processing, completed, failed), percent progress, and — once completed — the summary counts (deliverable, undeliverable, risky, unknown, catch-all). Report the summary to the user instead of listing individual addresses; the full result file can be downloaded from the ClearBounce dashboard.

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string",
      "description": "The jobId returned by verify_bulk"
    }
  },
  "required": [
    "jobId"
  ]
}

{
  "type": "object",
  "properties": {
    "jobId": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "description": "pending, processing, completed or failed"
    },
    "progress": {
      "type": "number",
      "description": "Percent complete, 0-100"
    },
    "totalEmails": {
      "type": "number"
    },
    "processedEmails": {
      "type": "number"
    },
    "deliverableCount": {
      "type": "number"
    },
    "undeliverableCount": {
      "type": "number"
    },
    "riskyCount": {
      "type": "number"
    },
    "unknownCount": {
      "type": "number"
    },
    "catchAllCount": {
      "type": "number"
    },
    "resultsUrl": {
      "type": "string",
      "description": "Dashboard page where the full result file can be downloaded"
    }
  },
  "required": [
    "jobId",
    "status",
    "progress"
  ]
}

Return the remaining verification credit balance for the account that owns the API key. Free.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean"
    },
    "credits": {
      "type": "number",
      "description": "Remaining verification credits on the account"
    },
    "purchaseUrl": {
      "type": "string",
      "description": "Where the user can buy more credits"
    },
    "notice": {
      "type": "string",
      "description": "Present only when the balance is low or empty"
    }
  },
  "required": [
    "credits"
  ]
}