Result Statuses

Every validation result tells you what it means for sending in four fields: status, sub_status, explanation and recommended_action. This page lists every value they can have.

The fields

The four fields are the last fields of every result: from the validation endpoint, from the getInfo tool of the MCP server, in the JSON results of bulk jobs and with sandbox keys.

{
    ...
    "status": "invalid",
    "sub_status": "mailbox_not_found",
    "explanation": "The mail server said that this mailbox does not exist.",
    "recommended_action": "suppress"
}

Statuses

Reserved statuses

spamtrap and abuse are reserved for future risk data (spam traps and addresses known to complain). They are not returned yet. If your code switches on status, give them a branch now, for example the same as do_not_mail.

Sub-statuses

An anti-spam block that is permanent says something about our connection to the mail server, not about the mailbox, which is why it is send_with_caution rather than retry_later.

New sub_status values may be added. Handle a value you do not know by its status and recommended_action.

When several apply

A result has one status and one sub-status. When more than one applies, the first match in this order wins:

1. The address has no valid format, or the mail server or DNS showed that mail to it bounces: invalid.
2. The address belongs to a disposable email provider: do_not_mail. This applies even when the mail server gave no answer, but not to privacy relay services (see 5), which are on some disposable lists.
3. The mail server gave no definite answer: unknown.
4. The mailbox is full: risky / mailbox_full.
5. The address belongs to a privacy relay service: valid / relay_address, even when disposable is true.
6. The domain is a catch-all domain: catch_all / accept_all.
7. The address is a role address: valid / role_based.
8. There is a did_you_mean suggestion: valid / possible_typo.
9. The address has a +tag: valid / alias.

For example, info@ on a catch-all domain is catch_all, not role_based; the role field is still true.

Status and state / reason

status and sub_status come from the same check as state and reason, which are still returned. They give a finer breakdown: reason low_deliverability, for example, can mean a catch-all domain, a disposable address or a full mailbox, and status tells them apart. The usual combinations:

A disposable address is do_not_mail whatever its state, unless it is undeliverable or belongs to a privacy relay service. What a check costs depends on state and reason, not on status; see Rate Limit & Quotas.

Catch-all on every plan

status is catch_all for an address on a catch-all domain on every plan, whether or not you set the catch_all parameter. The catch_all field itself stays null unless you send catch_all=1 on a plan that includes catch-all detection.

Using recommended_action

Bulk jobs

The JSON results of bulk jobs have all four fields. The CSV results have emailvalidation_status, emailvalidation_sub_status and emailvalidation_recommended_action as their last three columns; the explanation is in the JSON results only. The results of jobs that finished before these fields were added were saved then: they have only the earlier 15 fields and columns.

Testing

Sandbox keys return these fields too. Their test addresses cover each status, including a full mailbox, a greylisted check and an anti-spam block.