TrekMail Email Verifier API Quickstart

Use the API when verification should be part of your own product or import workflow. Create a token with verify:read and verify:write, keep it secret and call the same host that you use to sign in. In the examples, replace https://YOUR-TREKMAIL-HOST and YOUR_API_TOKEN.

1. Create a token

1. Open Dashboard → AI Agents & API.
2. Create a token.
3. Enable verify:read and verify:write.
4. Store the token securely. It is shown only once.

Send it with every request:

Authorization: Bearer YOUR_API_TOKEN

Keep the token in a secret store or environment variable. Do not put it in browser-side code, a public repository, a support ticket or an exported contact file. If you suspect it was exposed, revoke it and create a replacement in the dashboard.

2. Verify one address

Use POST /api/v1/verify for an immediate single-address result. Quick is the default when mode is omitted.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"person@example.com","mode":"quick"}'

The response contains stable top-level fields such as the address, status, trust score, provider, risk factors and remaining credits. The checks object records the detailed evidence and can vary when a check is unavailable or when Deep mode has extra information.

{
  "email": "person@example.com",
  "status": "valid",
  "trust_score": 82,
  "provider": "example.com",
  "risk_factors": ["no_dmarc"],
  "checks": {
    "syntax": {"pass": true, "score_impact": 0},
    "dmarc_record": {"pass": false, "score_impact": -10}
  },
  "credits_remaining": {
    "monthly": 99,
    "purchased": 0
  }
}

Read status and trust_score first. Treat individual check keys as supporting detail, not as a guarantee of inbox ownership or delivery.

The single endpoint has a 60-requests-per-minute route limit. If you are checking a user-entered address during signup, call it after basic client-side validation and show a plain error when the service is temporarily unavailable rather than blocking the person indefinitely.

3. Submit a bulk job

Bulk requests accept a JSON emails array, not a file upload. Include an idempotency key so a network retry does not create a second job.

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 58dfa0de-96eb-4521-a0f9-2e5eac6721ee" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"September contacts",
    "mode":"deep",
    "emails":["first@example.com","second@example.net"]
  }'

The list can contain up to 50,000 entries. TrekMail normalizes duplicates and rejects syntactically invalid entries from the job. The response reports the job ID, the accepted count, a small rejected sample, the charged credits and the Deep pricing breakdown.

{
  "job_id": 42,
  "total": 2,
  "status": "pending",
  "rejected_count": 0,
  "rejected_sample": [],
  "credits_charged": 4,
  "breakdown": {"probe": 2, "skip": 0, "deep_savings": 0}
}

probe is the count charged at the full Deep rate. skip is the count charged at the regular rate because the provider does not offer useful mailbox-level evidence. The response gives the authoritative cost for that submission.

Before submitting a full list, remove non-address values in your own importer. The API deduplicates addresses and reports a rejected count, but source validation produces a clearer audit trail. If the request times out from your application's point of view, retry the same bulk request with the same idempotency key and check the returned job ID before creating another submission.

4. Poll and download

Poll the job with GET /api/v1/verify/bulk/{jobId} until it reaches a terminal state:

curl https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The response includes status, total, processed, progress, summary, creation time and completion time. Completed and partial jobs include a paginated results array.

Poll at a sensible interval with backoff. A job can remain pending before work begins, and Deep work can take longer when a receiving provider offers additional evidence. Do not assume a fixed completion time from list size alone.

You can ask for a smaller result page or find a known address after results are available:

curl "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42?per_page=50&search=%40example.com" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Download a processed job as CSV:

curl -o results.csv \
  "https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/download?filter=safe" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The API export filters are all, safe and safe_risky (Safe + Valid + Risky).

To stop a pending or running job, use the cancellation endpoint. It refunds unprocessed work and keeps any processed rows:

curl -X POST https://YOUR-TREKMAIL-HOST/api/v1/verify/bulk/42/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Only delete a job when you want to remove its verifier record as well as its results. Cancel it first if it is still running, then use the delete endpoint with an idempotency key. The full reference shows both calls.

5. Handle the usual responses

• 402: the account needs more credits.
• 422: check the request body, the selected mode or a required idempotency key for a bulk request.
• 429: slow down and retry with backoff.
• 503: verification is temporarily unavailable. Retry later; a failed single-address verification is refunded.

A production integration checklist

1. Keep the token server-side and grant only the two verifier scopes needed.
2. Validate and normalize contact input before calling the bulk API.
3. Store the job ID, submitted-list identifier, idempotency key and returned credits_charged value.
4. Poll with backoff rather than a tight loop.
5. Store or process the CSV before its 15-day retention period ends.
6. Keep consent, opt-out and suppression decisions in your own application. A verifier result does not replace them.

Use the Email Verifier REST API Reference for all endpoints, scopes and response fields.