API Quickstart

Get up and running with programmatic email verification in under 5 minutes.

Prerequisites

You need an API token with the verify:read and verify:write scopes. API access is available on all plans, including Nano.

Step 1: Create your API token

1. Go to Dashboard → AI Agents & API
2. Click Create Token
3. Enable the verify:read and verify:write scopes
4. Copy the token — it is only shown once

Step 2: Verify a single email

curl -X POST https://trekmail.net/api/v1/verify \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "mode": "deep"}'

Step 3: Read the response

{
  "status": "safe",
  "trust_score": 95,
  "mode": "deep",
  "reason": "All checks passed",
  "checks": {
    "syntax": true,
    "mx": true,
    "mx_routable": true,
    "disposable": false,
    "role_based": false,
    "free_provider": false,
    "spf": true,
    "dmarc": true,
    "bounce_listed": false,
    "gibberish": false,
    "typo_suggestion": null,
    "plus_addressing": false,
    "dnsbl_listed": false,
    "domain_age_days": 365,
    "gravatar_exists": true,
    "smtp_status": "accepted"
  },
  "mx_host": "aspmx.l.google.com",
  "credits_remaining": 298
}

• trust_score — 0–100 confidence rating. Higher is better.
• status — one of safe, valid, risky, invalid, or unknown.
• checks — individual verification checks that contributed to the score. Deep mode includes additional fields like smtp_status.
• mode — "quick" or "deep". Omit the mode field to default to Quick. Deep mode costs 2 credits per email for business domains; for Gmail, Yahoo, Outlook, iCloud, AOL and similar free providers it's billed at the Quick rate of 1 credit because Deep can't add accuracy for those mailboxes (the providers don't allow per-mailbox verification). See Email Verifier Pricing.
• credits_remaining — your remaining credit balance after this verification.

Step 4: Submit a bulk list

curl -X POST https://trekmail.net/api/v1/verify/bulk \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: my-unique-key-123" \
  -F "file=@contacts.csv" \
  -F "mode=deep"

The Idempotency-Key header prevents duplicate submissions if your request is retried. The response includes a job_id you use to track progress.

{
  "job_id": 42,
  "total": 5000,
  "status": "pending",
  "rejected_count": 23,
  "rejected_sample": ["bad@", "incomplete"],
  "credits_charged": 6280,
  "breakdown": {
    "probe": 640,
    "skip": 4360,
    "deep_savings": 4360
  }
}

• credits_charged — actual credits deducted (not the naive count × 2).
• breakdown.probe — business-domain addresses that get the full Deep SMTP probe (billed at 2 credits each).
• breakdown.skip — free-provider addresses (Gmail, Yahoo, Outlook, iCloud, AOL, …) billed at 1 credit each — Deep can't add accuracy for them.
• breakdown.deep_savings — credits saved by this rule vs. flat 2-credit Deep pricing.

Step 5: Poll for results

curl https://trekmail.net/api/v1/verify/bulk/42 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "id": 42,
  "status": "completed",
  "total_count": 5000,
  "processed_count": 5000,
  "progress": 100,
  "results_summary": {
    "safe": 3200,
    "valid": 800,
    "risky": 400,
    "invalid": 600
  }
}

Step 6: Download the CSV

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

Use the filter parameter to download only specific segments: all (default), safe, or safe_risky (safe + valid + risky).

Error handling

MCP integration

All API endpoints have matching MCP tools, so you can use email verification directly from AI agents and assistants that support the Model Context Protocol.

Full API reference

For complete endpoint documentation, request/response schemas, and rate limits, see Email Verifier API Reference.