API Reference — request & response examples

All requests are authenticated with the Api-Key header. Error bodies use the shape { "detail": { "error", "code" } } — branch on code.

POST /api/v1/verify

Verify a single email (synchronous).

Request

curl -X POST https://email-verifier.sweego.io/api/v1/verify \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@example.com", "options": {"check_smtp": true, "suggest_typo": true, "include_email": true}}'

Response 200

{
  "email": "jane.doe@example.com",
  "category": "deliverable",
  "sub_category": null,
  "reason": null,
  "confidence_score": 0.98,
  "details": {
    "syntax": {
      "is_valid": true,
      "is_ascii": true,
      "error": null
    },
    "domain": {
      "name": "example.com",
      "exists": true,
      "has_mx": true,
      "mx_records": [
        "aspmx.l.google.com"
      ],
      "is_disposable": false,
      "is_free_provider": false,
      "is_catch_all": false,
      "provider": "Google Workspace",
      "domain_trust": null
    },
    "mailbox": {
      "is_role_based": false,
      "role_type": null,
      "is_alias": false,
      "alias_type": null
    },
    "random_pattern": {
      "is_random": false,
      "confidence": 0.0,
      "signals": [],
      "entropy": 3.2,
      "signal_details": []
    }
  },
  "suggestion": null,
  "metadata": {
    "verification_id": "a1b2c3d4-e5f6-4789-a0b1-c2d3e4f5a6b7",
    "verified_at": "2026-06-10T09:15:00Z",
    "processing_time_ms": 412
  }
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 402 — QUOTA_EXCEEDED

{
  "detail": {
    "error": "Monthly quota exhausted.",
    "code": "QUOTA_EXCEEDED",
    "used": 50000,
    "monthly_quota": 50000,
    "remaining": 0
  }
}

Response 429 — RATE_LIMIT_EXCEEDED

{
  "detail": {
    "error": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

POST /api/v1/verify/batch

Submit up to 1000 emails for asynchronous verification.

Request

curl -X POST https://email-verifier.sweego.io/api/v1/verify/batch \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["jane.doe@example.com", "john@example.org"], "webhook_url": "https://your-app.example.com/webhooks/ev", "retention_days": 7}'

Response 202

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "total_emails": 250,
  "estimated_time_seconds": 25,
  "check_status_url": "/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — BATCH_TOO_LARGE

{
  "detail": {
    "error": "Max 1000 emails per batch.",
    "code": "BATCH_TOO_LARGE"
  }
}

Response 429 — RATE_LIMIT_EXCEEDED

{
  "detail": {
    "error": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

POST /api/v1/verify/csv

Upload a CSV (up to 100 000 rows) for asynchronous verification.

Request

curl -X POST https://email-verifier.sweego.io/api/v1/verify/csv \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"
  -H "Content-Type: multipart/form-data" \
  -F "file=@contacts.csv" -F "retention_days=7"

Response 202

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "total_emails": 12000,
  "estimated_time_seconds": 1200,
  "check_status_url": "/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "detected_delimiter": ",",
  "detected_encoding": "utf-8",
  "email_column_name": "email",
  "has_header": true,
  "extra_column_names": [
    "first_name",
    "signup_date"
  ]
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — CSV_PARSE_ERROR

{
  "detail": {
    "error": "Could not detect a valid email column.",
    "code": "CSV_PARSE_ERROR"
  }
}

Response 413 — FILE_TOO_LARGE

{
  "detail": {
    "error": "CSV file exceeds the maximum size of 20 MB.",
    "code": "FILE_TOO_LARGE"
  }
}

Response 429 — RATE_LIMIT_EXCEEDED

{
  "detail": {
    "error": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED"
  }
}

GET /api/v1/jobs

List verification jobs (most recent first).

Request

curl -X GET https://email-verifier.sweego.io/api/v1/jobs \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "items": [
    {
      "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "completed",
      "source_type": "batch",
      "original_filename": null,
      "total_count": 250,
      "processed_count": 250,
      "created_at": "2026-06-10T09:10:00Z",
      "started_at": "2026-06-10T09:10:02Z",
      "completed_at": "2026-06-10T09:10:40Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — INVALID_STATUS_FILTER

{
  "detail": {
    "error": "Invalid status. Must be one of: ['cancelled', 'completed', 'failed', 'pending', 'processing']",
    "code": "INVALID_STATUS_FILTER"
  }
}

GET /api/v1/jobs/{job_id}

Fetch a job’s status and per-category stats.

Request

curl -X GET https://email-verifier.sweego.io/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "completed",
  "source_type": "batch",
  "total_count": 250,
  "processed_count": 250,
  "stats": {
    "total": 250,
    "processed": 250,
    "deliverable": 198,
    "undeliverable": 31,
    "risky": 12,
    "disposable": 4,
    "unknown": 3,
    "duplicate": 2,
    "invalid_syntax": 0,
    "random_pattern": 0,
    "high_risk": 0,
    "accept_all": 0
  },
  "created_at": "2026-06-10T09:10:00Z",
  "started_at": "2026-06-10T09:10:02Z",
  "completed_at": "2026-06-10T09:10:40Z",
  "webhook_url": null,
  "webhook_sent": false,
  "result_file_expires_at": "2026-06-11T09:10:40Z",
  "error_message": null,
  "original_filename": null,
  "download_url": "/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479/download"
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — INVALID_JOB_ID

{
  "detail": {
    "error": "Invalid job_id format (expected UUID).",
    "code": "INVALID_JOB_ID"
  }
}

Response 404 — JOB_NOT_FOUND

{
  "detail": {
    "error": "Job not found.",
    "code": "JOB_NOT_FOUND"
  }
}

GET /api/v1/jobs/{job_id}/results

Paginated results for a job.

Request

curl -X GET https://email-verifier.sweego.io/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479/results \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "job_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "total": 250,
  "offset": 0,
  "limit": 100,
  "category_filter": null,
  "include_email": false,
  "results": [
    {
      "row_number": 1,
      "email": null,
      "category": "deliverable",
      "sub_category": null,
      "reason": null,
      "confidence_score": 0.98,
      "extra_columns": {
        "first_name": "Jane"
      }
    },
    {
      "row_number": 2,
      "email": null,
      "category": "undeliverable",
      "sub_category": "no_mx_record",
      "reason": "no_mx_record",
      "confidence_score": 0.99,
      "extra_columns": {
        "first_name": "John"
      }
    }
  ]
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — INVALID_JOB_ID

{
  "detail": {
    "error": "Invalid job_id format (expected UUID).",
    "code": "INVALID_JOB_ID"
  }
}

Response 404 — JOB_NOT_FOUND

{
  "detail": {
    "error": "Job not found.",
    "code": "JOB_NOT_FOUND"
  }
}

GET /api/v1/jobs/{job_id}/download

Download the result CSV (returns a file).

Request

curl -X GET https://email-verifier.sweego.io/api/v1/jobs/f47ac10b-58cc-4372-a567-0e02b2c3d479/download \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200 — binary CSV (Content-Type: text/csv).

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}

Response 400 — INVALID_JOB_ID

{
  "detail": {
    "error": "Invalid job_id format (expected UUID).",
    "code": "INVALID_JOB_ID"
  }
}

Response 404 — JOB_NOT_FOUND

{
  "detail": {
    "error": "Job not found.",
    "code": "JOB_NOT_FOUND"
  }
}

Response 409 — JOB_NOT_COMPLETED

{
  "detail": {
    "error": "Job is not completed yet (status: processing).",
    "code": "JOB_NOT_COMPLETED"
  }
}

Response 410 — RESULT_FILE_EXPIRED

{
  "detail": {
    "error": "Result file has expired and is no longer available.",
    "code": "RESULT_FILE_EXPIRED"
  }
}

GET /api/v1/usage

Read your own current-month consumption.

Request

curl -X GET https://email-verifier.sweego.io/api/v1/usage \
  -H "Api-Key: ev_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response 200

{
  "client_id": "9b2e5c1a-7d4f-4a2b-8c3e-1f0a6d5b4c3d",
  "period_month": "2026-06",
  "billable_units": 1234,
  "monthly_quota": 50000,
  "usage_ratio": 0.0247,
  "over_quota": false,
  "hard_cap": false,
  "billing_note": "manual_postpaid: soft cap, never blocks"
}

Response 401 — MISSING_API_KEY

{
  "detail": {
    "error": "API key required. Provide it via the 'Api-Key' header.",
    "code": "MISSING_API_KEY"
  }
}

Response 403 — INSUFFICIENT_SCOPE

{
  "detail": {
    "error": "This API key lacks the required scope 'verify'.",
    "code": "INSUFFICIENT_SCOPE"
  }
}