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 and includes SMTP verification plus additional checks.
• 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,
  "status": "pending",
  "total_count": 5000,
  "deduplicated_from": 5023,
  "mode": "deep",
  "credits_deducted": 10000,
  "message": "Job created. Poll GET /api/v1/verify/bulk/42 for status."
}

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.