VFX

API Reference

Verifex

API Reference

Everything you need to start validating emails in under 2 minutes.

Base URL

https://verifex-puce.vercel.app
/api/v1

Response envelope

Every response is wrapped in { "success": true, "data": ... } on success, or { "success": false, "error": { "message": "...", "code": "..." } } on failure.

Validate Email

Validates an email address with a format check followed by a DNS MX record lookup. Both checks must pass for valid: true.

POST/api/v1/validate

Submit an email address for validation. Returns detailed check results and lookup duration.

Auth

X-API-Key header. Rate limited to 60 requests per 60 seconds per key.

Request

curl -X POST https://verifex-puce.vercel.app
/api/v1/validate \
  -H "X-API-Key: vfx_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Valid response

{
  "success": true,
  "data": {
    "valid": true,
    "email": "user@example.com",
    "domain": "example.com",
    "checks": { "format": true, "mx": true },
    "mx_records": ["mail.example.com"],
    "duration_ms": 18
  }
}

Invalid response

{
  "success": true,
  "data": {
    "valid": false,
    "email": "user@fakedomain.xyz",
    "domain": "fakedomain.xyz",
    "checks": { "format": true, "mx": false },
    "mx_records": [],
    "reason": "No MX records found for domain",
    "duration_ms": 22
  }
}

API Keys

Manage your API keys. Keys are shown once at creation and cannot be retrieved again. Maximum 10 keys per account. These endpoints require a browser session — they are not callable via curl.

GET/api/v1/keys

List all keys for the authenticated user. Never returns the key hash.

Auth

Supabase session cookie (browser only).

Response

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Production",
      "key_prefix": "vfx_live_a1b2",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "last_used_at": "2024-01-20T14:22:00Z"
    }
  ]
}

POST/api/v1/keys

Create a new API key. The raw key is returned exactly once — copy it immediately.

Auth

Supabase session cookie (browser only).

Request body

{ "name": "Production" }

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-...",
    "name": "Production",
    "key": "vfx_live_a1b2c3d4...",
    "key_prefix": "vfx_live_a1b2",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "last_used_at": null
  }
}

DELETE/api/v1/keys

Revoke an API key. Sets is_active to false. The row is retained for audit trail.

Auth

Supabase session cookie (browser only).

Request body

{ "id": "a1b2c3d4-..." }

Response

{ "success": true, "data": null }

Usage

Query your validation history. Returns an aggregate summary plus a paginated log of recent calls. Full email addresses are never stored — only the domain.

GET/api/v1/usage

Fetch usage summary and recent activity. Query params: limit (default 20, max 100), offset (default 0).

Auth

Supabase session cookie (browser only).

Response

{
  "success": true,
  "data": {
    "summary": { "total": 214, "valid": 189, "invalid": 25 },
    "logs": [
      {
        "id": "uuid",
        "email_domain": "example.com",
        "result": "valid",
        "duration_ms": 18,
        "created_at": "2024-01-20T14:22:00Z"
      }
    ],
    "total": 214
  }
}

Account

Account deletion is permanent. All API keys and usage logs are removed in FK-safe order before the auth user is deleted.

DELETE/api/v1/account

Permanently delete the authenticated account and all associated data.

Auth

Supabase session cookie (browser only).

Response

{ "success": true, "data": null }

Error Codes

All errors use a consistent JSON shape with a human-readable message and a machine-readable code.

Code	Status	Meaning
VALIDATION_ERROR	400	Request body failed schema validation
UNAUTHORIZED	401	Missing or invalid API key or session
FORBIDDEN	403	Valid credentials but insufficient permissions
NOT_FOUND	404	Requested resource does not exist
CONFLICT	409	Resource already exists or state conflict
RATE_LIMITED	429	Too many requests — 60 per minute per API key
INTERNAL_ERROR	500	Unexpected server error