> ## 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**<br />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**.
</Tip>

## 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](/api-reference/email/verify-a-single-email-address) with `metadata=true`.
* [Upload a file](/api-reference/email/upload-a-batch-file-for-email-verification) with the same option for metadata in each output row.
* [Read the batch workflow](/api-reference/v2/email-verification-overview) for status polling and downloads.


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