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

# Email Verification statuses and metadata

> Understand verification results, provider and MX details, and the reason behind each result.

Request `?metadata=true` to include the details behind an email verification.
**Metadata is included at no extra cost**, for both single checks and batch
files. It does not add a charge per field or change the price of a result.

## Verification results and credits

The primary `status` determines the verification charge on both PAYG and AYCE.
AYCE includes unlimited contact retrieval; email verification uses the credit
prices below on either plan.

| `status` | Meaning | Credits per result |
| - | - | - |
| `Valid` | The check found evidence that the email account exists. | **1 credit** |
| `Invalid` | The check found that the account or its mail domain is unavailable. | **1 credit** |
| `Unknown` | The check could not reach a reliable conclusion. Keep this separate from Invalid. | **Free** 0 credits |

These values are case-sensitive. Use `status` as the result of the check and
`reason` to understand it. Requesting metadata keeps the same prices.

For example, 100 checks that return 70 Valid, 20 Invalid, and 10 Unknown cost
**90 credits**, with or without metadata.

An unsuccessful check can return only `email` and `status: "Unknown"`, even
when you requested metadata. Treat missing details as unavailable.

## Metadata fields

| Field | Values or type | How to interpret it |
| - | - | - |
| `domain` | String | The domain of the submitted address. |
| `timestamp` | String | When the verification result was produced. A timestamp without a timezone does not identify a UTC offset. |
| `mx_record_present` | Boolean | Whether an MX record was detected. This describes domain routing; use the primary status to decide how to handle the email. |
| `mx_record_checked` | String | The MX hostname that was checked, such as `aspmx.l.google.com`. This is a hostname, not a verification status or timestamp. |
| `email_provider` | `Google`, `Microsoft`, or `Unknown` | The detected email provider. Provider `Unknown` means the provider was not classified; read `status` separately. |
| `security_gateway` | String | A detected mail gateway or routing service, such as Proofpoint or Mimecast. Empty, null, or `Unknown` means no gateway was identified. |
| `reason` | String | An explanation of the primary result. See the common reasons below. |

Fields can be empty or null when the information is unavailable. An MX record
or a recognized provider alone does not confirm that an individual mailbox
exists.

> [!TIP]
>
> **Use `email_provider` to group recipients for outbound campaigns.**
> If you send at high volume with Smartlead or Instantly, match your sending
> inbox to the recipient's provider when possible:
>
> * Send to `Microsoft` recipients from Microsoft inboxes.
> * Send to `Google` recipients from Google inboxes.
>
> [Smartlead](https://helpcenter.smartlead.ai/en/articles/72-understanding-esp-matching-in-smartlead)
> and [Instantly](https://help.instantly.ai/en/articles/7044069-email-service-providers-matching)
> support provider matching to help improve inbox placement. Customers have
> anecdotally reported deliverability improvements of **25% or more** with
> this approach. These are customer reports, rather than a measured benchmark;
> results vary by campaign. Provider `Unknown` cannot be used to make this match.
>
> Request `metadata=true` on your original verification call to get
> `email_provider` **at no extra cost**.

## Common reasons

`reason` is an open string. Handle unrecognized values without failing your
integration; this table describes common values returned by the verifier.

| `reason` | Meaning | Suggested handling |
| - | - | - |
| `user_account_found` | The check detected the account. | Read the accompanying status before using the address. |
| `user_account_not_found` | The check did not find the account. | Exclude an Invalid result from your send list. |
| `user_account_could_not_be_detected` | The check could not determine whether the account exists. | Keep the result as inconclusive; retry later if needed. |
| `consumer_email` | The address uses a personal email domain, outside the verifier's business-email checks. | Treat the Unknown result as unverified. |
| `domain_does_not_exist` | The domain could not be found in DNS. | Review the address and domain spelling. |
| `no_mx_records_found` | No mail exchange records were found for the domain. | Review the domain's mail setup. |
| `no_nameservers_found` | The DNS lookup could not find usable nameservers. | Review the domain and its DNS setup. |
| `unknown_mx_records` | The MX lookup could not complete reliably. | Treat the routing information as unresolved. |
| Empty, null, or `N/A` | No more specific reason was supplied. | Use the primary status; do not infer another result. |

## Batch output

For CSV output, `status` uses Valid, Invalid, and Unknown. The JSON batch
output can also contain `Error` when an individual check fails. Treat that
value as inconclusive; it adds **0 verification credits**.

A row's verification status is separate from its job's processing status.
For example, a COMPLETED job can contain Unknown results. A job status of
ERROR describes a failed batch, rather than an Invalid email address.

## Next steps

* [Verify one address](https://docs.revenuebase.ai/api-reference/email/verify-a-single-email-address.md) with `metadata=true`.
* [Upload a file](https://docs.revenuebase.ai/api-reference/email/upload-a-batch-file-for-email-verification.md) with the same option for metadata in each output row.
* [Read the batch workflow](https://docs.revenuebase.ai/api-reference/v2/email-verification-overview.md) for status polling and downloads.


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