> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# メール検証API
> Cleariflowの最高クラスのメール検証APIで、受信トレイへの到達率を向上させ、メーリングリストを健全に保ちましょう。
## クイックスタート
リクエストを行うには、固有の `api_key` と確認したい `email` を指定するだけで十分です。他に必要なパラメータはありません。
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = jane.doe@acme-corp.com
```
リクエストが成功すると、アドレスに関する利用可能なすべてのインサイトが返されます。
```json theme={"system"}
{
"email": "jane.doe@acme-corp.com",
"autocorrect": "",
"deliverability": "DELIVERABLE",
"quality_score": 0.85,
"is_valid_format": {
"value": true,
"text": "TRUE"
},
"is_free_email": {
"value": false,
"text": "FALSE"
},
"is_disposable_email": {
"value": false,
"text": "FALSE"
},
"is_role_email": {
"value": false,
"text": "FALSE"
},
"is_catchall_email": {
"value": false,
"text": "FALSE"
},
"is_mx_found": {
"value": true,
"text": "TRUE"
},
"is_smtp_valid": {
"value": true,
"text": "TRUE"
}
}
```
### リクエストパラメータ
個人のAPI認証情報です。キーはCleariflow製品ごとにスコープが分かれているため、メール検証のキーではIPジオロケーションAPIなど他のAPIへのリクエストは認可されません。
検証したいメールアドレスです。
自動修正を無効にするオプションフラグです。`auto_correct=false` を設定するとオフになります。デフォルトでは有効です。
### レスポンスパラメータ
レスポンスは、コンパクトで標準化された [JSON](https://www.json.org/json-en.html) 形式で返されます。
リクエストで送信された `email` をエコーします。
タイプミスの可能性が検出された場合の修正候補です（例：[johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)）。候補がない場合は空です。
アドレスがメールを受信できるかどうかのCleariflowの評価です。取り得る値：`DELIVERABLE`、`UNDELIVERABLE`、`UNKNOWN`。`DELIVERABLE` には SMTP 検証の成功が必要です。MX レコードはあるが SMTP でメールボックスを確認できない場合（大手プロバイダでよくある）は `UNKNOWN` になります。すべてのプランで同じ検証を実行します。無料プランは月間クォータとレート制限のみが異なります（エラーコード 422、429 を参照）。
アドレス品質を示す `0`〜`0.99` の小数スコアです。使い捨てアドレスは約 `0.05` に制限され、SMTP 未確認時は最大 `0.55` です。
アドレスが標準パターン `local@domain.tld` に一致する場合に true です。要素の欠落や無効な文字がある場合は `false` になります。
ドメインが無料メールプロバイダー（Gmail、Yahooなど）に属する場合に true です。
ドメインが使い捨て・一時的な受信箱プロバイダーのリスト（Mailinator、Yopmailなど）に含まれる場合に true です。
ローカル部が個人ではなく役割アカウント（`team@`、`sales@`、`info@` など）と思われる場合に true です。
ドメインが [キャッチオール](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account) として設定されている場合に true です。
ドメインに [MXレコード](https://en.wikipedia.org/wiki/MX_record) が存在する場合に true です。
[SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) 検証が成功した場合に true です。SMTPが失敗しても他のチェックが通過した場合、結果は `UNKNOWN` になることがあります。SMTPの失敗のみを理由にサインアップやフォーム送信をブロックすることは推奨しません。
## リクエスト例
### 例：タイプミスの可能性
この例では、送信されたアドレスにタイプミスの可能性が検出されたリクエストを示します。
タイプミスの可能性が見つかった場合でも、他のすべてのチェック（無料メール、使い捨てドメインなど）は、修正候補ではなく元のアドレスに対して実行されます。
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith@gmial.con
```
成功時のレスポンスは次のとおりです。
```json theme={"system"}
{
"email": "johnsmith@gmial.con",
"autocorrect": "johnsmith@gmail.com",
"deliverability": "UNKNOWN",
"quality_score": 0.4,
"is_valid_format": {
"value": true,
"text": "TRUE"
},
"is_free_email": {
"value": false,
"text": "FALSE"
},
"is_disposable_email": {
"value": false,
"text": "FALSE"
},
"is_role_email": {
"value": false,
"text": "FALSE"
},
"is_catchall_email": {
"value": false,
"text": "FALSE"
},
"is_mx_found": {
"value": false,
"text": "FALSE"
},
"is_smtp_valid": {
"value": false,
"text": "FALSE"
}
}
```
### 例：無効なフォーマット
この例では、基本的なフォーマットチェックに失敗するアドレスを示します。`is_valid_format` が `false` の場合、後続のチェック（`is_free_email`、`is_role_email` など）はスキップされ、`false` として報告されます。
```bash theme={"system"}
https://emailvalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& email = johnsmith
```
成功時のレスポンスは次のとおりです。
```json theme={"system"}
{
"email": "johnsmith",
"autocorrect": "",
"deliverability": "UNDELIVERABLE",
"quality_score": 0.0,
"is_valid_format": {
"value": false,
"text": "FALSE"
},
"is_free_email": {
"value": false,
"text": "FALSE"
},
"is_disposable_email": {
"value": false,
"text": "FALSE"
},
"is_role_email": {
"value": false,
"text": "FALSE"
},
"is_catchall_email": {
"value": false,
"text": "FALSE"
},
"is_mx_found": {
"value": false,
"text": "FALSE"
},
"is_smtp_valid": {
"value": false,
"text": "FALSE"
}
}
```
## 一括アップロード（CSV）
APIを直接呼び出したくない場合は、CSV一括アップローダーをご利用ください。処理が完了すると結果がメールで送信されます。
CSVをアップロードする際は、次のガイドラインに従ってください。
* メールアドレスを最初の列に配置してください。
* 空行を削除してください。
* 1行に1アドレスのみ記載してください。
* ファイルは最大50,000行までに制限してください。
## レスポンスおよびエラーコード
エラーはコードと人間が読める説明を含むJSON形式で返されます。一般的なコードを以下に示します。
| Code | Type | Details |
| ---- | --------------------- | ---------------------------------- |
| 200 | OK | リクエストが正常に完了しました。 |
| 400 | Bad request | リクエストの形式が不正、または無効です。 |
| 401 | Unauthorized | 認証に失敗しました。通常はAPIキーが欠落しているか無効です。 |
| 422 | Quota reached | クォータを使い切りました（無料プランでクレジット不足など）。 |
| 429 | Too many requests | レート制限を超えました（無料プランでは1秒あたり最大1リクエスト）。 |
| 500 | Internal server error | サーバー側で予期しないエラーが発生しました。 |
| 503 | Service unavailable | サービスが一時的に利用できません。 |
## その他の注意事項
プランに関する注意：すべてのプラン（無料・有料）で、MX、SMTP、キャッチオール検出を含む同じ検証を実行します。
課金に関する注意：評価したメールアドレスごとに、結果に関わらず1リクエストあたり1クレジットを消費します。無効なアドレス（例：「fda3346ds」）を送信した場合でも1クレジットとしてカウントされます。