API Reference

https://api.emailverify.ai/v1

Authorization: Bearer YOUR_API_KEY

curl -X POST https://api.emailverify.ai/v1/verify \
  -H "Authorization: Bearer bv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 3600
  }
}

POST /verify

{
  "email": "user@example.com",
  "smtp_check": true,
  "timeout": 5000
}

{
  "email": "user@example.com",
  "status": "valid",
  "result": {
    "deliverable": true,
    "valid_format": true,
    "valid_domain": true,
    "valid_mx": true,
    "disposable": false,
    "role": false,
    "catchall": false,
    "free": false,
    "smtp_valid": true
  },
  "score": 0.95,
  "reason": null,
  "credits_used": 1
}

POST /verify/bulk

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "smtp_check": true,
  "webhook_url": "https://your-app.com/webhooks/emailverify"
}

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 3,
  "processed": 0,
  "valid": 0,
  "invalid": 0,
  "unknown": 0,
  "credits_used": 3,
  "created_at": "2025-01-15T10:30:00Z"
}

GET /verify/bulk/{job_id}

{
  "job_id": "job_abc123xyz",
  "status": "processing",
  "total": 1000,
  "processed": 450,
  "valid": 380,
  "invalid": 50,
  "unknown": 20,
  "progress_percent": 45,
  "created_at": "2025-01-15T10:30:00Z"
}

{
  "job_id": "job_abc123xyz",
  "status": "completed",
  "total": 1000,
  "processed": 1000,
  "valid": 850,
  "invalid": 100,
  "unknown": 50,
  "progress_percent": 100,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:35:00Z"
}

GET /verify/bulk/{job_id}/results

{
  "job_id": "job_abc123xyz",
  "total": 1000,
  "limit": 100,
  "offset": 0,
  "results": [
    {
      "email": "user1@example.com",
      "status": "valid",
      "result": {
        "deliverable": true,
        "disposable": false,
        "role": false
      },
      "score": 0.95
    },
    {
      "email": "user2@example.com",
      "status": "invalid",
      "result": {
        "deliverable": false,
        "reason": "mailbox_not_found"
      },
      "score": 0.10
    }
  ]
}

GET /credits

{
  "available": 9500,
  "used": 500,
  "total": 10000,
  "plan": "Professional",
  "resets_at": "2025-02-01T00:00:00Z",
  "rate_limit": {
    "requests_per_hour": 10000,
    "remaining": 9850
  }
}

POST /webhooks

{
  "url": "https://your-app.com/webhooks/emailverify",
  "events": ["verification.completed", "bulk.completed"],
  "secret": "your-webhook-secret"
}

GET /webhooks

DELETE /webhooks/{webhook_id}

{
  "event": "bulk.completed",
  "timestamp": "2025-01-15T10:35:00Z",
  "data": {
    "job_id": "job_abc123xyz",
    "status": "completed",
    "total": 1000,
    "valid": 850,
    "invalid": 100,
    "unknown": 50
  },
  "signature": "sha256=..."
}

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional context (optional)"
  }
}

// 正確
const apiKey = process.env.EMAILVERIFY_API_KEY;

// 錯誤 - 不要這樣做
const apiKey = 'bv_live_xxx';

async function verifyWithRetry(email, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await verify(email);
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

// 正確 - 單次 API 呼叫
const job = await client.verifyBulk(emails);

// 錯誤 - 多次個別呼叫
for (const email of emails) {
  await client.verify(email);
}

// 使用 webhook 提交
const job = await client.verifyBulk(emails, {
  webhookUrl: 'https://your-app.com/webhook',
});