> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailglyph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email Validation

> Validate individual email addresses, process bulk validation files, and monitor validation credits.

Email Validation helps you decide whether an address should enter your product, contact list, or sending workflow. MailGlyph checks syntax, domain health, MX records, disposable domains, personal domains, plus addressing, random-looking local parts, typo suggestions, and SMTP mailbox status when available.

Use a **secret API key** (`sk_...`) for all Email Validation API and SDK calls.

> [!WARNING]
>
> Never run Email Validation from browser code with a secret key. Call MailGlyph from your backend or serverless function.

## Validate one address

Use single-email validation when a user signs up, submits a form, or changes an email address.

```bash theme={null}
curl --request POST \
  --url https://api.mailglyph.com/v1/verify \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{"email":"user@gmail.com"}'
```

A successful response includes an overall `valid` boolean and detailed signals:

```json theme={null}
{
  "success": true,
  "data": {
    "email": "user@gmail.com",
    "valid": true,
    "validationMethod": "smtp",
    "smtpStatus": "Valid",
    "smtpDiagnosis": "Mailbox exists and can receive mail.",
    "creditsConsumed": 1,
    "isDisposable": false,
    "isTypo": false,
    "isPlusAddressed": false,
    "isRandomInput": false,
    "isCatchAll": false,
    "isGreylisted": false,
    "domainExists": true,
    "hasMxRecords": true,
    "reasons": []
  }
}
```

## Interpret results

Use `valid` for the first decision, then inspect the detailed fields for product-specific rules.

| Field | How to use it |
| - | - |
| `valid` | Overall validation result. Use this for allow/block decisions when you do not need custom logic. |
| `smtpStatus` | Mailbox-level status: `Valid`, `Invalid`, `Unknown`, `Catch All`, or `Grey-listed`. |
| `validationMethod` | `smtp` means mailbox-level validation was attempted. `local` means local checks produced the result. |
| `suggestedEmail` | Correction to show when `isTypo` is true. |
| `isDisposable` | Flag temporary email domains that often produce poor list quality. |
| `isRandomInput` | Flag token-like or generated local parts. |
| `domainExists` and `hasMxRecords` | Confirm that the domain can receive email. |
| `creditsConsumed` | Net credits charged for this validation. `Unknown` results are refunded and return `0`. |

> [!TIP]
>
> Treat `Catch All` and `Grey-listed` as deliverable but lower-confidence results. They consume one validation credit because MailGlyph completed SMTP-level validation.

## Validate a file

Use bulk validation for contact imports, list cleanup, or scheduled hygiene jobs. Upload a TXT, CSV, or XLSX file up to 90MB.

```bash theme={null}
curl --request POST \
  --url https://api.mailglyph.com/v1/verify/files \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY" \
  --form "file=@emails.csv"
```

The response is a job record. Store the `id` and poll it from your backend.

```json theme={null}
{
  "success": true,
  "data": {
    "id": "8a607588-1d7c-4d4f-9807-2a625fb20b14",
    "status": "QUEUED",
    "originalFilename": "emails.csv",
    "localEmailCount": 2500,
    "reservedCredits": 2500,
    "readyForDownload": false
  }
}
```

## Poll and download results

```bash theme={null}
curl --request GET \
  --url https://api.mailglyph.com/v1/verify/files/8a607588-1d7c-4d4f-9807-2a625fb20b14 \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY"
```

When `status` is `COMPLETED` and `readyForDownload` is true, download the results:

```bash theme={null}
curl --request GET \
  --url "https://api.mailglyph.com/v1/verify/files/8a607588-1d7c-4d4f-9807-2a625fb20b14/download?filter=valid&format=csv" \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY" \
  --output valid-emails.csv
```

Download filters are `all`, `valid`, `invalid`, `unknown`, and `catchall`. Filtered downloads are CSV only. XLS is available only when `filter=all`.

## Continue jobs that need credits

Bulk jobs reserve credits from the detected email count. If a job pauses with `ACTION_REQUIRED`, add credits in the dashboard, then continue it:

```bash theme={null}
curl --request POST \
  --url https://api.mailglyph.com/v1/verify/files/8a607588-1d7c-4d4f-9807-2a625fb20b14/continue \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY"
```

Unknown and duplicate emails are not charged in the final reconciliation.

## Check credits and ledger

Check the current project balance:

```bash theme={null}
curl --request GET \
  --url https://api.mailglyph.com/v1/verification-credits \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY"
```

Review recent credit activity with cursor pagination:

```bash theme={null}
curl --request GET \
  --url "https://api.mailglyph.com/v1/verification-credits/ledger?limit=25" \
  --header "Authorization: Bearer $MAILGLYPH_SECRET_KEY"
```

Ledger responses do not include raw email addresses.

## Use the SDKs

The official SDKs expose an Email Validation client for single and bulk validation:

* [Node.js Email Validation](https://docs.mailglyph.com/sdks/nodejs/email-validation.md)
* [Go Email Validation](https://docs.mailglyph.com/sdks/go/email-validation.md)
* [Python Email Validation](https://docs.mailglyph.com/sdks/python/email-validation.md)
* [PHP Email Validation](https://docs.mailglyph.com/sdks/php/email-validation.md)

For endpoint details, see the [Email Validation API reference](https://docs.mailglyph.com/api-reference/verifications/verifyEmail.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.