API Reference

Complete email checker API reference. Endpoints, parameters, response codes for email verification and validation.

EmailVerify API は、強力なメール検証機能を提供する RESTful サービスです。すべての API リクエストは HTTPS 経由で行う必要があります。

ベース URL

https://api.emailverify.ai/v1

認証

すべての API リクエストには、Authorization ヘッダーに Bearer トークンを使用した認証が必要です：

Authorization: Bearer YOUR_API_KEY

API キーは EmailVerify ダッシュボードから取得できます。

例

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"}'

レート制限

プラン	リクエスト/時	リクエスト/日
Free	100	1,000
Starter	1,000	10,000
Professional	10,000	100,000
Enterprise	カスタム	カスタム

レート制限情報はレスポンスヘッダーに含まれます：

ヘッダー	説明
`X-RateLimit-Limit`	許可された最大リクエスト数
`X-RateLimit-Remaining`	ウィンドウ内の残りリクエスト数
`X-RateLimit-Reset`	制限がリセットされる Unix タイムスタンプ

レート制限を超えると、429 Too Many Requests レスポンスが返されます：

{
  "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`	string	はい	-	検証するメールアドレス
`smtp_check`	boolean	いいえ	`true`	SMTP メールボックス検証を実行
`timeout`	integer	いいえ	`5000`	リクエストタイムアウト（ミリ秒、最大: 30000）

レスポンス

{
  "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
}

レスポンスフィールド

フィールド	型	説明
`email`	string	検証されたメールアドレス
`status`	string	検証ステータス：`valid`、`invalid`、`unknown`、`accept_all`
`result`	object	詳細な検証結果
`score`	number	信頼スコア（0.0 - 1.0）
`reason`	string	invalid/unknown ステータスの理由（null 可）
`credits_used`	integer	消費されたクレジット数

result オブジェクトのフィールド

フィールド	型	説明
`deliverable`	boolean	メールがメッセージを受信できるかどうか
`valid_format`	boolean	メールの構文が有効かどうか
`valid_domain`	boolean	ドメインが存在するかどうか
`valid_mx`	boolean	ドメインに MX レコードがあるかどうか
`disposable`	boolean	使い捨てサービスからのメールかどうか
`role`	boolean	役職ベースのメール（info@、support@）かどうか
`catchall`	boolean	ドメインがすべてのメールを受け入れるかどうか
`free`	boolean	無料プロバイダーからのメールかどうか
`smtp_valid`	boolean	SMTP 検証に合格したかどうか

一括メール検証

複数のメールアドレスを検証用に送信します。進捗追跡用のジョブ ID が返されます。

POST /verify/bulk

リクエスト

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

パラメータ

パラメータ	型	必須	デフォルト	説明
`emails`	array	はい	-	メールアドレスの配列（最大: 10,000）
`smtp_check`	boolean	いいえ	`true`	SMTP 検証を実行
`webhook_url`	string	いいえ	-	完了通知を受け取る URL

レスポンス

{
  "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"
}

ジョブステータス値

ステータス	説明
`pending`	ジョブはキューに入っています
`processing`	ジョブは処理中です
`completed`	ジョブは正常に完了しました
`failed`	ジョブは失敗しました（error フィールドを参照）

一括ジョブ結果の取得

完了した一括ジョブの検証結果を取得します。

GET /verify/bulk/{job_id}/results

クエリパラメータ

パラメータ	型	デフォルト	説明
`limit`	integer	100	ページあたりの結果数（最大: 1000）
`offset`	integer	0	開始位置
`status`	string	-	ステータスでフィルタ：`valid`、`invalid`、`unknown`

レスポンス

{
  "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
  }
}

Webhook

Webhook の作成

POST /webhooks

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

Webhook の一覧

GET /webhooks

Webhook の削除

DELETE /webhooks/{webhook_id}

Webhook イベント

イベント	説明
`verification.completed`	単一メール検証が完了
`bulk.completed`	一括ジョブが完了
`bulk.failed`	一括ジョブが失敗
`credits.low`	クレジットがしきい値を下回った

Webhook ペイロード

{
  "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=..."
}

検証ステータス

ステータス	意味	推奨アクション
`valid`	メールが存在し、メッセージを受信可能	送信しても安全
`invalid`	メールが存在しないか受信不可	リストから削除
`unknown`	有効性を判定できなかった	後で再試行するか注意して使用
`accept_all`	ドメインがすべてのメールを受け入れる（キャッチオール）	バウンスを監視

エラーレスポンス

すべてのエラーは一貫したフォーマットに従います：

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

HTTP ステータスコード

コード	説明
`200`	成功
`400`	Bad Request - 無効なパラメータ
`401`	Unauthorized - 無効または欠落した API キー
`403`	Forbidden - 権限不足
`404`	Not Found - リソースが存在しない
`429`	Too Many Requests - レート制限を超過
`500`	Internal Server Error
`503`	Service Unavailable

エラーコード

コード	HTTP ステータス	説明
`INVALID_API_KEY`	401	API キーが無効または欠落
`RATE_LIMIT_EXCEEDED`	429	リクエスト数が多すぎる
`INSUFFICIENT_CREDITS`	403	クレジット不足
`INVALID_EMAIL`	400	メール形式が無効
`INVALID_REQUEST`	400	リクエストボディが不正
`JOB_NOT_FOUND`	404	一括ジョブ ID が見つからない
`TIMEOUT`	504	検証がタイムアウト

ベストプラクティス

1. 環境変数を使用する

API キーをハードコードしないでください：

// Good
const apiKey = process.env.EMAILVERIFY_API_KEY;

// Bad - don't do this
const apiKey = 'bv_live_xxx';

2. レート制限を処理する

指数バックオフを実装：

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;
    }
  }
}

3. 複数メールには一括を使用する

10 件以上のメールを検証する場合は、一括エンドポイントを使用：

// Good - single API call
const job = await client.verifyBulk(emails);

// Bad - many individual calls
for (const email of emails) {
  await client.verify(email);
}

4. 一括ジョブには Webhook を実装する

常にポーリングするのではなく、Webhook を使用：

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

API Reference

Node.js

Python

Go

PHP

Java

TypeScript

クイックスタートガイド

検証タイプ

統合ガイド

On this page