Product guidance
Email Checker API: Choosing Between Single, Multi and Bulk Requests
A developer decision guide to single, multi-address and asynchronous bulk email checks, plus how to turn each outcome into application logic.
How to pick the right email checker API request for each job and map deliverable, undeliverable and undetermined outcomes into code.
An email checker API should be called in one of three shapes, chosen by who is waiting and how many addresses you have. Use a single check (POST /api/v1/check) when a person is waiting on one address, a synchronous multi-address check (POST /api/v1/batch-check, 1–100 addresses, results in input order) when a small group arrives together, and an asynchronous bulk task (POST /api/v1/bulk-tasks, then status polling) when the addresses already sit in a file. Whatever the shape, design your code around three outcomes rather than a yes/no flag: deliverable, undeliverable, and undetermined, with malformed input handled before the call. Each completed result describes the address at check time only.
What an email checker API answers, and what it leaves to you
Most pages that rank for this topic list features and stop there. The integration question is narrower: what does one call actually decide, and what does your application still own?
EmailCheckPro's Email Deliverability Check returns a completed result of deliverable (the address could receive mail at check time) or undeliverable. Email Avatar Check adds a public-avatar signal, but only for Gmail, Yandex and Mail.ru addresses.
Your application still owns three jobs:
- Format screening. A complete address has a local part, an
@sign and a domain. Malformed input is a form error, not an undeliverable verdict, so catch it before spending a call. - A confirmation link or your own consent records cover that.
- Timing. A result belongs to the moment of the check. Store the date next to the outcome so later jobs know how old it is.
Keeping these boundaries in the code, not just in the documentation, avoids the most common integration bugs described below.
Choosing the email checker API request shape
The three request shapes are not interchangeable, and picking the wrong one is the usual cause of slow forms or fragile import jobs.
| Situation | Request | How results arrive | Watch out for |
|---|---|---|---|
| A signup, checkout or profile form | POST /api/v1/check |
In the same response | Keep the call server-side and set your own timeout |
| An admin pastes a short list, or a job picks up records edited since the last run | POST /api/v1/batch-check (1–100 addresses) |
In the same response, in input order | Items without a completed result are not undeliverable |
| A CRM export, a list migration or any prepared file | POST /api/v1/bulk-tasks, then GET /api/v1/bulk-tasks/{id} |
Later, as one result CSV | Poll no more often than every 30 seconds |
A quick way to decide:
- Is someone waiting on screen? Use the single endpoint for just the address they typed.
- Do the addresses arrive together and fit in 100? Send one multi request. It is still synchronous: a larger single call, not a small bulk task.
- Is the source already a file, or far beyond a few hundred rows? Submit a bulk task and let a background worker collect the result. Per-product task limits apply and are listed in the API documentation.
- Does the job need avatars? Filter the list to supported Gmail, Yandex and Mail.ru domains first. An unsupported domain is rejected before a realtime charge, and in an avatar bulk file it makes preparation fail, with the reservation returned.
For a few hundred addresses that are not in a file, either several multi requests or the dashboard's realtime check, which handles up to 500 addresses, is reasonable.
Mapping outcomes into application logic
Collapsing results into a boolean is where most integrations go wrong. A small state type keeps the meaning intact:
| State | Source | Signup form | Import or sending pipeline |
|---|---|---|---|
| Malformed | Your own format check | Ask for a correction inline | Move the row to a fix-up queue |
| Deliverable | Completed check | Continue | Keep, with the check date |
| Undeliverable | Completed check | Ask for another address, offer a retry | Suppress routine sends and look for a current address |
| Undetermined | Check could not be settled, for example a catch-all address | Accept with a flag | Hold in a review group and re-check later |
| Not completed | Timeout, network error or service failure | Accept with a flag | Retry later from a queue |
Three rules follow from the documentation:
- In a single realtime check, an undetermined address returns a business code instead of a result and is not charged. Treat that branch as its own state, not as an error to retry in a tight loop.
- In a multi response, every item says whether a completed result exists. Only items with one carry deliverable or undeliverable; the rest belong in the undetermined or not-completed branch.
- Invalid, failed and undetermined checks are not charged, so retrying them later costs nothing but time. Schedule the retry instead of repeating it immediately.
Running asynchronous bulk tasks without surprises
A bulk task is a small state machine, and it belongs in a background worker rather than a web request.
- Prepare the file. Write TXT or CSV with one complete email address per line. Invalid and duplicate lines are removed during preparation, but stripping obvious junk first makes your own counts easier to reconcile.
- Submit and record. Save the task reference returned by
POST /api/v1/bulk-tasksin your database, together with the source file name, the product used and the submission time. A worker that crashes can then resume instead of resubmitting. - Poll patiently. Query
GET /api/v1/bulk-tasks/{id}no more often than every 30 seconds. A scheduled job that checks once and sleeps fits this better than a loop holding a connection open. - Download promptly. A successful task provides one CSV at a download link that lasts 12 hours. If the link expires, query the same task again for a fresh link rather than uploading the file a second time.
- Merge by address. Because preparation can drop lines, join the result CSV back to your records by email address, never by row number.
The deliverability CSV pairs each address with its outcome. The avatar CSV also states whether a public avatar was found and gives an avatar link, which can be empty even when an avatar is present, so treat an empty link as a normal value.
Operating the integration day to day
Once the request shapes and states are right, a few operating habits keep the integration quiet:
- Server-side keys only. The API key spends the account balance, which is shared by web checks, REST calls, bulk tasks and MCP access. Never ship it in browser or mobile code.
- Check at the point of change. Check when an address is created or edited, then reuse the stored result inside your own re-check window instead of calling on every page view.
- Fail open at the form, closed in the pipeline. If a check is slow or unsettled during signup, let the person continue with a flagged address. In a sending pipeline, hold flagged rows until they have a completed result.
- Protect your own endpoint. If your app exposes a "check this address" route, rate-limit it and return consistent messages. The OWASP email validation guidance warns against letting forms reveal whether an account exists.
- Give AI clients the MCP endpoint.
https://emailcheckpro.com/mcpsupports single checks, up to 100 addresses per call, product listing and balance queries. File-based bulk work stays on the web workflow or REST API.
Current request limits and usage details are published in the EmailCheckPro API documentation; read them there rather than hard-coding assumptions.
A format check that matches the API's expectations
The cheapest call is the one you never make for malformed input. Two references help you choose a sensible screen:
- The WHATWG HTML standard defines the pattern browsers use for
type="email"fields. It deliberately departs from the full mail standards to stay practical, which makes it a reasonable server-side baseline too. - RFC 5321 describes the address forms used in mail transport. Treat it as a format reference for edge cases such as quoted local parts, not as a description of how any checking service works.
In practice: trim whitespace, remove trailing punctuation copied from documents, lowercase the domain, keep the local part as entered, and reject only input that clearly lacks a local part, an @ or a domain. Over-strict patterns that reject plus signs or long top-level domains turn away real users and should be avoided.
FAQ
When should teams switch from multi-address calls to a bulk task?
Switch when the addresses already live in a file, or when a job would need many consecutive multi calls just to work through a list. Multi requests suit groups of up to 100 that arrive together and need answers in the same response. Bulk tasks suit prepared exports that can wait, because the result arrives later as one CSV and the worker only needs to poll status every 30 seconds or less often.
How should an application store email checker API results?
Keep the address as entered, the product used, the outcome in plain words, the check date and the source of the address. That record lets support explain a decision, lets re-check jobs pick the oldest results first, and keeps undetermined or not-completed rows separate from undeliverable ones. Avoid storing raw response payloads as the only record, because other systems would then depend on the API's format.
Can a deliverable result replace a confirmation email?
No. A deliverable result informs whether the address could receive mail at check time, and the check itself sends nothing. A confirmation link answers a different question: whether the person who entered the address controls it and agrees to receive messages. Many signup flows use the check to catch dead addresses before sending, then rely on confirmation for consent and ownership.
What is the safest way to retry checks that did not complete?
Put them in a queue with a delay instead of retrying in the request that failed. Undetermined, failed and invalid checks are not charged, but immediate retries rarely change the outcome and can slow your own service. A scheduled retry, with a cap on attempts and a note of each attempt's date, keeps the record honest and lets reviewers see which addresses still have no completed result.
Learn More
Choose the product information that fits the next step in your workflow.