Bulk verification API

Overview

Bulk verification is a four-stage workflow: reserve an upload target, upload the file, submit a job, then poll until result files are ready. Files bypass the MailTooth API process and stream directly to object storage, while the API remains the source of truth for ownership, credits, status, progress, and downloads.

The developer API currently exposes submission, listing, polling, and downloads. Stop, restart, and resume controls remain dashboard operations, although their state can appear in job responses.

Authentication

Send an active developer API key to every MailTooth API endpoint. Use either x-api-key or a Bearer token. Keep the key in a server-side secret store; never place it in a browser bundle, source repository, uploaded file, or signed-storage request.

Signed upload and download URLs are temporary credentials of their own. Do not attach your MailTooth API key when calling those URLs.

End-to-end flow

Complete these requests in order:

1. Create an upload target and save its fileId, URL, and headers.
2. PUT the exact file bytes to the signed storage URL.
3. Submit the fileId as an asynchronous job and save its id.
4. Poll the job until it reaches a terminal status.
5. Request fresh download links and save either or both CSV files.

Do not submit the job until the storage PUT returns a successful 2xx response. Uploading and job submission are separate operations.

Input file requirements

Verification types

standard is the default. Deprecated enriched and pro inputs map to deepcheck.

1. Create an upload target

Describe the file before uploading it. For CSV, emailColumn is required. For plain text it must be omitted. The response contains a file ID plus a signed PUT target.

curl --request POST 'https://api.mailtooth.com/verify/bulk/uploads' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "fileName": "contacts.csv",
    "contentType": "text/csv",
    "sizeBytes": 128,
    "verificationType": "standard",
    "emailColumn": "email"
  }'

{
  "fileId": "2d66fc31-73c2-4adb-9f22-ec78c7097198",
  "uploadUrl": "https://storage.example.com/bulk/...signed-query...",
  "headers": {
    "Content-Type": "text/csv",
    "Content-Length": "128"
  },
  "expiresAt": "2026-09-13T08:30:00.000Z",
  "maxFileSizeBytes": 10485760
}

The upload URL lasts 15 minutes. Response expiresAt is the 30-day file-retention deadline, not the upload URL expiry.

2. Upload the file

PUT the original bytes to uploadUrl with every returned header. This request goes to object storage and does not use your MailTooth API key.

curl --request PUT 'UPLOAD_URL_FROM_RESPONSE' \
  --header 'Content-Type: text/csv' \
  --header 'Content-Length: 128' \
  --upload-file './contacts.csv'

• Do not change line endings, reserialize CSV, or compress after calculating sizeBytes.
• Keep Content-Type and Content-Length identical to the returned headers.
• Treat uploadUrl as a secret and discard it after the PUT succeeds.
• If it expires before upload succeeds, create a new upload target.

3. Submit the job

Submit the uploaded fileId. The API confirms stored size, validates and counts records, reserves available credits atomically, creates the durable job, and publishes it to the queue.

curl --request POST 'https://api.mailtooth.com/verify/bulk/jobs' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{"fileId":"2d66fc31-73c2-4adb-9f22-ec78c7097198"}'

{
  "id": "1f35fcb4-7ca0-4b2c-b582-e325b54636bb",
  "fileId": "2d66fc31-73c2-4adb-9f22-ec78c7097198",
  "retryOfJobId": null,
  "attemptNumber": 1,
  "retryStrategy": null,
  "startRecord": 0,
  "fileName": "contacts.csv",
  "emailColumn": "email",
  "status": "queued",
  "totalRecords": 3,
  "verificationType": "standard",
  "recordsReserved": 3,
  "reservedCredits": 3,
  "refundedCredits": 0,
  "processedRecords": 0,
  "processedRecordsOverall": 0,
  "remainingRecords": 3,
  "deliverableRecords": 0,
  "riskyRecords": 0,
  "undeliverableRecords": 0,
  "unknownRecords": 0,
  "professionalRecords": 0,
  "personalRecords": 0,
  "unclassifiedRecords": 0,
  "progressPercent": 0,
  "warning": null,
  "failureReason": null,
  "downloadsAvailable": false,
  "canStop": true,
  "canRetry": false,
  "canResume": false,
  "resumeFromRecord": 0,
  "expiresAt": "2026-09-13T08:30:00.000Z",
  "startedAt": null,
  "completedAt": null,
  "createdAt": "2026-08-14T08:31:00.000Z",
  "updatedAt": "2026-08-14T08:31:00.000Z"
}

4. Track progress

Poll with the submitted job ID. Progress is checkpointed, so counts may advance in batches rather than after every email.

curl 'https://api.mailtooth.com/verify/bulk/jobs/1f35fcb4-7ca0-4b2c-b582-e325b54636bb' \
  --header 'x-api-key: YOUR_API_KEY'

{
  "id": "1f35fcb4-7ca0-4b2c-b582-e325b54636bb",
  "fileId": "2d66fc31-73c2-4adb-9f22-ec78c7097198",
  "retryOfJobId": null,
  "attemptNumber": 1,
  "retryStrategy": null,
  "startRecord": 0,
  "fileName": "contacts.csv",
  "emailColumn": "email",
  "status": "processing",
  "totalRecords": 3,
  "verificationType": "standard",
  "recordsReserved": 3,
  "reservedCredits": 3,
  "refundedCredits": 0,
  "processedRecords": 2,
  "processedRecordsOverall": 2,
  "remainingRecords": 1,
  "deliverableRecords": 1,
  "riskyRecords": 0,
  "undeliverableRecords": 1,
  "unknownRecords": 0,
  "professionalRecords": 1,
  "personalRecords": 1,
  "unclassifiedRecords": 0,
  "progressPercent": 67,
  "warning": null,
  "failureReason": null,
  "downloadsAvailable": false,
  "canStop": true,
  "canRetry": false,
  "canResume": false,
  "resumeFromRecord": 2,
  "expiresAt": "2026-09-13T08:30:00.000Z",
  "startedAt": "2026-08-14T08:31:01.000Z",
  "completedAt": null,
  "createdAt": "2026-08-14T08:31:00.000Z",
  "updatedAt": "2026-08-14T08:31:05.000Z"
}

Lifecycle statuses

List recent jobs

GET /jobs returns up to 100 jobs for the API-key account, newest first. Every item has the same job shape.

curl 'https://api.mailtooth.com/verify/bulk/jobs' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Job field reference

5. Download results

Request links only when downloadsAvailable is true. URLs expire after 15 minutes; call this endpoint again for fresh links.

curl 'https://api.mailtooth.com/verify/bulk/jobs/1f35fcb4-7ca0-4b2c-b582-e325b54636bb/downloads' \
  --header 'x-api-key: YOUR_API_KEY'

{
  "expiresAt": "2026-09-13T08:30:00.000Z",
  "verifiedRecordsUrl": "https://storage.example.com/.../verified.csv?signed-query",
  "allResultsUrl": "https://storage.example.com/.../all-results.csv?signed-query"
}

curl --location 'VERIFIED_RECORDS_URL' \
  --output './contacts-verified.csv'

curl --location 'ALL_RESULTS_URL' \
  --output './contacts-all-results.csv'

Response expiresAt is the result-retention deadline, separate from each signed URL's shorter lifetime.

Result file contents

Both CSV exports preserve every input column in its original order, then append normalized verification and enrichment columns.

Enrichment columns in both files

verification_score is blank when the selected tier does not produce a score. Missing enrichment uses an empty cell or its documented unknown fallback.

Credits and partial jobs

Submission reserves credits before queueing. If the account can afford at least one record but not the full file, the API reserves as many as possible, returns a warning, and finishes as partial. If it cannot afford one record, submission returns HTTP 402 and creates no job.

Read reservedCredits, refundedCredits, and warning rather than inferring billing from progress.

Errors and recovery

{
  "statusCode": 400,
  "message": "Result files are not available.",
  "error": "Bad Request"
}

• Fix 400 responses before retrying the request.
• Treat 401 and 402 as configuration or account-state failures.
• After a submission timeout, list recent jobs before retrying POST /jobs; the original may have succeeded.
• Retry unexpected 500 responses with exponential backoff and jitter.

Production integration guidance

• Persist fileId until submission and job id through the retention window.
• Poll every 2–5 seconds initially, then back off for long jobs.
• Stop polling only on completed, partial, stopped, or failed.
• Use downloadsAvailable—not status alone—to request result links.
• Generate download links just in time and redact them from logs.
• Read CSV headers by name instead of relying on appended positions.
• Surface warning and failureReason to operators.
• Download before expiresAt; files are retained for 30 days.