Developer guides
Build email verification into your product
Step-by-step guides with working code for the API.
Getting started
Start here
Your first API call and how to test it without spending credits.
Quickstart: verify your first email with the SimpleCold API
Create an API key, check it, and verify your first address with cURL, Node.js and Python. Covers the response envelope, categories and reasons.
Read the guideTest your integration with free test email addresses
Use SimpleCold's test addresses to exercise every result path in development and CI without spending credits. Includes Jest and pytest examples.
Read the guideAPI
Work with the API
Single, batch and bulk checks, slow servers and errors, with working code.
Verify a list of emails in Python with the batch endpoint
Send up to 50 addresses per request from Python, stay inside the 10-per-minute rate limit, collect processing results and write a clean CSV at the end.
Read the guideRun a bulk verification job end to end
Upload a CSV to the SimpleCold bulk endpoint, poll job status with sensible backoff, and download results as CSV or JSON. cURL, Node.js and Python.
Read the guideHandle processing and no-response results correctly
Why some checks return processing, how to collect the final answer without paying twice, and what to do when a result comes back as no_response.
Read the guideError handling and rate limits for the SimpleCold API
Every error the SimpleCold API returns, what causes it, and how to retry safely. Includes rate-limit headers, backoff code and a fail-open pattern.
Read the guideWorkflows
Build it into your process
Turn results into send decisions and keep lists clean over time.
Clean a CRM export with the bulk API and re-import the results
Export contacts from HubSpot or any CRM, verify them with the SimpleCold bulk endpoint, and re-import category and reason fields by record ID.
Read the guideMap verification categories and statuses to send decisions
A reference for turning SimpleCold categories and status codes into send, review, suppress and retry rules, with per-use-case tables and code.
Read the guideVerify emails at sign-up with Node.js
Build an Express route that checks addresses on a sign-up form, shows typo suggestions, blocks bad addresses and handles slow mail servers correctly.
Read the guidePolling patterns for bulk jobs and pending checks
Restart-safe polling for SimpleCold bulk jobs and pending checks: a jobs table, a sweeper, backoff from nextUpdateAt, and a fallback behind webhooks.
Read the guideCheck your list before you send it
Start with 200 free credits. Pay per credit after that.