API Reference

Verify email addresses programmatically using TrekMail's REST API. Endpoints require an API token with the appropriate scope: verify:read for read-only access, verify:write for mutations.

Authentication

Include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Scopes must be explicitly enabled when creating or editing your API token. They are not granted by default.

• verify:read — check credits, list jobs, view job status and results
• verify:write — submit verifications, cancel jobs, delete jobs (also grants read access)

Endpoints

GET /api/v1/verify/credits

Returns the current credit balance for your account. Requires verify:read scope.

Response (200):

{
  "monthly_limit": 5000,
  "monthly_used": 1200,
  "monthly_remaining": 3800,
  "purchased_balance": 10000,
  "total_available": 13800,
  "plan": "pro",
  "resets_at": "2026-04-01T00:00:00Z"
}

POST /api/v1/verify

Verify a single email address in real-time. Response is padded to a minimum of 200ms to prevent timing attacks.

Request:

{
  "email": "user@example.com",
  "mode": "deep"
}

Response (200):

{
  "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,
    "name_detected": true,
    "profanity_detected": false,
    "domain_has_website": true,
    "spam_trap_score": 0,
    "breached_domain": false,
    "smtp_status": "accepted"
  },
  "mx_host": "aspmx.l.google.com",
  "smtp_status": "accepted"
}

Deep-mode-only response fields:

These fields are only present when mode is "deep". In Quick mode, they are omitted from the response.

Credits: Quick mode deducts 1 credit. Deep mode deducts 2 credits.

POST /api/v1/verify/bulk

Submit a list of emails for async bulk verification. Returns immediately with a job ID.

Request:

{
  "emails": ["a@example.com", "b@test.com", "..."],
  "name": "March campaign list",
  "mode": "deep"
}

• Maximum 50,000 emails per request
• Duplicates are automatically removed
• If an identical list was submitted within 24 hours, the existing job is returned

Response (201):

{
  "job_id": 42,
  "status": "pending",
  "total_count": 1500,
  "deduplicated_from": 1523,
  "mode": "deep",
  "credits_deducted": 3000,
  "message": "Job created. Poll GET /api/v1/verify/bulk/42 for status."
}

Response (200) — duplicate detected:

{
  "job_id": 41,
  "status": "completed",
  "message": "Duplicate list detected. Returning existing job.",
  "duplicate": true
}

GET /api/v1/verify/bulk/{jobId}

Check the status of a bulk verification job. Requires verify:read scope.

Query parameters:

• page — results page number (default: 1)
• search — filter results by partial email match (e.g. ?search=@gmail.com)

Response (200) — processing:

{
  "id": 42,
  "name": "March campaign list",
  "status": "processing",
  "total_count": 1500,
  "processed_count": 750,
  "progress": 50,
  "created_at": "2026-03-23T10:00:00Z",
  "completed_at": null,
  "results_summary": null
}

Response (200) — completed:

{
  "id": 42,
  "name": "March campaign list",
  "status": "completed",
  "total_count": 1500,
  "processed_count": 1500,
  "progress": 100,
  "created_at": "2026-03-23T10:00:00Z",
  "completed_at": "2026-03-23T12:00:00Z",
  "results_summary": {
    "safe": 1200,
    "valid": 150,
    "risky": 80,
    "invalid": 60,
    "unknown": 10
  },
  "results": {
    "data": [
      {
        "email": "user@example.com",
        "status": "safe",
        "trust_score": 95,
        "reason": "All checks passed",
        "mx_host": "aspmx.l.google.com"
      }
    ],
    "current_page": 1,
    "last_page": 15,
    "per_page": 100,
    "total": 1500
  }
}

Results are included when the job is completed, partial, or cancelled with results. Results are paginated (100 per page). Use ?page=2 to paginate. Use ?search=term to filter results by partial email match.

GET /api/v1/verify/bulk/{jobId}/download

Download results as a CSV file. Available for completed, partial, and cancelled jobs (with results).

Query parameters:

• filter — all (default), safe, or safe_risky

Response: Streamed CSV with columns: email, status, score, reason, mx_host. Deep mode jobs include an additional smtp_status column.

GET /api/v1/verify/bulk

List all verification jobs for your account with pagination. Requires verify:read scope.

Query parameters:

• page — page number (default: 1)
• per_page — results per page (default: 25, max: 100)
• status — filter by job status: pending, processing, completed, cancelled, failed

Response (200):

{
  "jobs": [
    {
      "job_id": 42,
      "name": "March campaign list",
      "status": "completed",
      "total": 1500,
      "processed": 1500,
      "progress": 100,
      "created_at": "2026-03-23T10:00:00Z",
      "completed_at": "2026-03-23T12:00:00Z"
    },
    {
      "job_id": 43,
      "name": "Newsletter cleanup",
      "status": "processing",
      "total": 3000,
      "processed": 1200,
      "progress": 40,
      "created_at": "2026-03-23T14:00:00Z",
      "completed_at": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 8,
    "last_page": 1
  }
}

POST /api/v1/verify/bulk/{jobId}/cancel

Cancel a running verification job and refund credits for unprocessed emails. Requires verify:write scope.

Response (200):

{
  "status": "cancelled",
  "credits_refunded": 40
}

Response (409) — job already complete:

{
  "error": "job_already_complete",
  "message": "Cannot cancel a completed job."
}

DELETE /api/v1/verify/bulk/{jobId}

Permanently delete a verification job and all its results. Intended for GDPR compliance. Requires verify:write scope.

The job must not be actively processing. Cancel it first if needed.

Response (200):

{
  "deleted": true
}

Response (409) — job still processing:

{
  "error": "job_still_processing",
  "message": "Cancel the job before deleting. Use POST /api/v1/verify/bulk/{jobId}/cancel first."
}

Error codes

Rate limits

• Single verification: 60 requests/minute per account
• Bulk submission: 10 requests/minute per account
• Job status polling: 120 requests/minute per account

MCP Tools

Eight MCP tools are available for AI agent integration:

See AI Agents & API for MCP setup instructions.