{"openapi":"3.1.0","info":{"title":"Bouncebuster API","version":"1.0.0","description":"Simple, affordable email verification. Authenticate with a Bearer API key (create one in the dashboard under API keys). One credit is charged per billable result - duplicates and `unknown` results are never charged.","contact":{"name":"Bouncebuster","url":"https://bouncebuster.io"}},"servers":[{"url":"https://app.bouncebuster.io/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Verification","description":"Verify single addresses or small batches."},{"name":"Lists","description":"Bulk verification jobs."},{"name":"Account","description":"Plan and credit information."}],"paths":{"/verify":{"post":{"tags":["Verification"],"summary":"Verify a single email","operationId":"verifyEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","example":"jane@example.com"}}}}}},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","example":"jane@example.com"},"status":{"type":"string","enum":["valid","invalid","catch-all","disposable","unknown"],"description":"The verification verdict. Only `unknown` is never billed."},"reason":{"type":"string","example":"ok","description":"Granular reason behind the status (does not affect billing)."},"catch_all":{"type":"boolean","description":"True when the domain accepts every recipient."},"catch_all_domain":{"type":"boolean","description":"Alias of `catch_all`; the domain is accept-all so a single mailbox can’t be confirmed over SMTP."},"role_based":{"type":"boolean","description":"e.g. info@, support@, sales@"},"free_provider":{"type":"boolean","description":"gmail.com, outlook.com, …"},"disposable":{"type":"boolean"},"smtp_provider":{"type":["string","null"],"example":"google","description":"Mailbox provider inferred from MX records (google, microsoft, zoho, …)."},"mx_found":{"type":"boolean","description":"Whether an MX (or implicit A) record was found."},"mx_record":{"type":["string","null"],"example":"aspmx.l.google.com","description":"Primary (highest-priority) MX hostname."},"did_you_mean":{"type":["string","null"],"example":"jane@gmail.com","description":"Suggested correction when the domain looks like a common typo."},"domain_age_days":{"type":["integer","null"],"example":9331,"description":"Domain registration age in days (best-effort, via RDAP)."},"billable":{"type":"boolean"},"cached":{"type":"boolean","description":"Served from the 30-day result cache."},"credits_charged":{"type":"integer","example":1}},"required":["email","status","reason","billable"]}}}},"400":{"description":"Missing email","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"402":{"description":"Out of credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/verify/batch":{"post":{"tags":["Verification"],"summary":"Verify up to 100 emails synchronously","operationId":"verifyBatch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","items":{"type":"string"},"maxItems":100,"example":["jane@example.com","bad@nope.invalid"]}}}}}},"responses":{"200":{"description":"Batch results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","example":"jane@example.com"},"status":{"type":"string","enum":["valid","invalid","catch-all","disposable","unknown"],"description":"The verification verdict. Only `unknown` is never billed."},"reason":{"type":"string","example":"ok","description":"Granular reason behind the status (does not affect billing)."},"catch_all":{"type":"boolean","description":"True when the domain accepts every recipient."},"catch_all_domain":{"type":"boolean","description":"Alias of `catch_all`; the domain is accept-all so a single mailbox can’t be confirmed over SMTP."},"role_based":{"type":"boolean","description":"e.g. info@, support@, sales@"},"free_provider":{"type":"boolean","description":"gmail.com, outlook.com, …"},"disposable":{"type":"boolean"},"smtp_provider":{"type":["string","null"],"example":"google","description":"Mailbox provider inferred from MX records (google, microsoft, zoho, …)."},"mx_found":{"type":"boolean","description":"Whether an MX (or implicit A) record was found."},"mx_record":{"type":["string","null"],"example":"aspmx.l.google.com","description":"Primary (highest-priority) MX hostname."},"did_you_mean":{"type":["string","null"],"example":"jane@gmail.com","description":"Suggested correction when the domain looks like a common typo."},"domain_age_days":{"type":["integer","null"],"example":9331,"description":"Domain registration age in days (best-effort, via RDAP)."},"billable":{"type":"boolean"},"cached":{"type":"boolean","description":"Served from the 30-day result cache."},"credits_charged":{"type":"integer","example":1}},"required":["email","status","reason","billable"]}},"summary":{"type":"object","properties":{"total":{"type":"integer"},"credits_charged":{"type":"integer"}}}}}}}},"422":{"description":"Batch too large","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/lists":{"get":{"tags":["Lists"],"summary":"List recent bulk jobs","operationId":"listLists","responses":{"200":{"description":"Recent lists","content":{"application/json":{"schema":{"type":"object","properties":{"lists":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","parsing","processing","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"counts":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"catch_all":{"type":"integer"},"disposable":{"type":"integer"},"unknown":{"type":"integer"},"duplicate":{"type":"integer"},"billable":{"type":"integer"}}},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"downloads":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Per-category download URLs (present once the list completes)."}}}}}}}}}}},"post":{"tags":["Lists"],"summary":"Create a bulk verification job","operationId":"createList","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"name":{"type":"string","example":"newsletter-2026.csv"},"emails":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"202":{"description":"List accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","parsing","processing","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"counts":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"catch_all":{"type":"integer"},"disposable":{"type":"integer"},"unknown":{"type":"integer"},"duplicate":{"type":"integer"},"billable":{"type":"integer"}}},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"downloads":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Per-category download URLs (present once the list completes)."}}}}}}}}},"/lists/{id}":{"get":{"tags":["Lists"],"summary":"Get a list","operationId":"getList","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","parsing","processing","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"counts":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"catch_all":{"type":"integer"},"disposable":{"type":"integer"},"unknown":{"type":"integer"},"duplicate":{"type":"integer"},"billable":{"type":"integer"}}},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"downloads":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Per-category download URLs (present once the list completes)."}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/lists/{id}/download/{category}":{"get":{"tags":["Lists"],"summary":"Download an export file","operationId":"downloadListExport","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"category","in":"path","required":true,"schema":{"type":"string","enum":["cleaned","cleaned-catch-all","all","valid","invalid","catch-all","disposable","unknown"]}}],"responses":{"200":{"description":"CSV file","content":{"text/csv":{}}},"302":{"description":"Redirect to a presigned download URL"},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Get account plan and credits","operationId":"getAccount","responses":{"200":{"description":"Account info","content":{"application/json":{"schema":{"type":"object","properties":{"team":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"plan":{"type":"string"},"subscription_status":{"type":"string"},"credits":{"type":"object","properties":{"monthly":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"}}},"period":{"type":"object","properties":{"start":{"type":["string","null"],"format":"date-time"},"end":{"type":["string","null"],"format":"date-time"}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key, e.g. `Authorization: Bearer bb_live_…`"}},"schemas":{"Verification":{"type":"object","properties":{"email":{"type":"string","example":"jane@example.com"},"status":{"type":"string","enum":["valid","invalid","catch-all","disposable","unknown"],"description":"The verification verdict. Only `unknown` is never billed."},"reason":{"type":"string","example":"ok","description":"Granular reason behind the status (does not affect billing)."},"catch_all":{"type":"boolean","description":"True when the domain accepts every recipient."},"catch_all_domain":{"type":"boolean","description":"Alias of `catch_all`; the domain is accept-all so a single mailbox can’t be confirmed over SMTP."},"role_based":{"type":"boolean","description":"e.g. info@, support@, sales@"},"free_provider":{"type":"boolean","description":"gmail.com, outlook.com, …"},"disposable":{"type":"boolean"},"smtp_provider":{"type":["string","null"],"example":"google","description":"Mailbox provider inferred from MX records (google, microsoft, zoho, …)."},"mx_found":{"type":"boolean","description":"Whether an MX (or implicit A) record was found."},"mx_record":{"type":["string","null"],"example":"aspmx.l.google.com","description":"Primary (highest-priority) MX hostname."},"did_you_mean":{"type":["string","null"],"example":"jane@gmail.com","description":"Suggested correction when the domain looks like a common typo."},"domain_age_days":{"type":["integer","null"],"example":9331,"description":"Domain registration age in days (best-effort, via RDAP)."},"billable":{"type":"boolean"},"cached":{"type":"boolean","description":"Served from the 30-day result cache."},"credits_charged":{"type":"integer","example":1}},"required":["email","status","reason","billable"]},"List":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","parsing","processing","completed","failed"]},"progress":{"type":"integer","minimum":0,"maximum":100},"counts":{"type":"object","properties":{"total":{"type":"integer"},"processed":{"type":"integer"},"valid":{"type":"integer"},"invalid":{"type":"integer"},"catch_all":{"type":"integer"},"disposable":{"type":"integer"},"unknown":{"type":"integer"},"duplicate":{"type":"integer"},"billable":{"type":"integer"}}},"error":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"downloads":{"type":"object","additionalProperties":{"type":"string","format":"uri"},"description":"Per-category download URLs (present once the list completes)."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}