# Response Fields

Successful single email/domain checks return a JSON object. Fields depend on input validity, requested features, and available data.

## Core fields

| Field | Type | Description |
| --- | --- | --- |
| `format` | bool | Whether the submitted email or domain has valid syntax. |
| `alias` | bool | Whether the email contains a `+` alias (e.g. `user+tag@gmail.com`). Only present when `true`. Plus-aliases on Gmail/Outlook/Hotmail/Live/MSN/iCloud are additionally checked against known temp-mail base accounts — see [Plus-Alias Detection](https://docs.disify.com/api/plus-alias.md). |
| `domain` | string | The domain extracted from the email address, or the submitted domain in domain mode. |
| `disposable` | bool | Whether the email or domain is detected as disposable, including individual plus-alias checks in email mode. This is the disposable verdict; paid [privacy-relay policy](https://docs.disify.com/api/forwarding.md) is separate. |
| `dns` | bool | Whether usable mail DNS was found. If `signals` includes `dns_indeterminate`, a false value is inconclusive and should be retried. |
| `whitelist` | bool | `true` when the domain is on the trusted-provider whitelist. May be `false` or omitted; treat an absent value as `false`. |
| `role` | bool | Whether the email uses a role-based prefix (e.g. `info@`, `support@`, `admin@`). Always `false` for domain-only checks. |
| `free` | bool | Whether the domain is a known free email provider (e.g. Gmail, Yahoo, Outlook). |
| `confidence` | int | Confidence score (0–100) of the disposable detection. See [Confidence Scoring](https://docs.disify.com/api/confidence.md). |
| `signals` | array | Detection and availability signals, which can appear with either disposable verdict. Omitted when empty. See [Detection Signals](https://docs.disify.com/api/signals.md). |
| `typo_suggestion` | string | Typo correction for common domain misspellings (e.g. `gmial.com` → `gmail.com`). Only present when a typo is detected. Email mode only. |
| `domain_info` | object | Domain metadata: `tld` (string), `is_subdomain` (bool), `parent_domain` (string \| null). |
| `mx_info` | array | The domain's MX hostnames. Omitted when no MX hostnames are available. |
| `requires_upgrade` | array | Requested [premium features](https://docs.disify.com/guide/premium-features.md) your current plan doesn't include. Only present when one or more features are denied. |
| `upgrade_url` | string | Link to the pricing page. Present alongside `requires_upgrade`. |
| `upgrade_message` | string | Human-readable note explaining the denied features need a paid plan. Present alongside `requires_upgrade`. |
| `unsupported_features` | array | Requested features that don't exist on any plan yet (`smtp`, `catch_all`). Only present when you request one of them. |
| `unsupported_message` | string | Note explaining that `unsupported_features` aren't available on any plan. Present alongside `unsupported_features`. |
| `temporarily_unavailable_features` | array | Requested features that could not be calculated temporarily. Core validation still completes; retry these features later. |

**Absent fields**

Check HTTP status and `format` first. A `format: false` result may omit later checks; missing decision fields in a valid-format result are unexpected and must not be treated as a safe address.

Absent `alias` or `whitelist` means false; absent `signals` or `typo_suggestion` means no associated detail. Premium fields depend on plan access, requested checks, and available data. Retry checks listed in `temporarily_unavailable_features`.

## Paid privacy forwarding

`forwarding` and `blocked` are automatically included on paid valid-format single checks. See [Privacy Forwarding](https://docs.disify.com/api/forwarding.md) for setup, providers, and examples.

| Field | Type | Meaning |
| --- | --- | --- |
| `forwarding.detected` | bool \| null | `true`: known match. `false`: no known match. `null`: inconclusive, such as temporary DNS failure or mixed matching/nonmatching MX servers. |
| `forwarding.type` | string \| null | `privacy_alias` on a match; otherwise `null`. |
| `forwarding.provider` | string \| null | Stable provider ID on a match; otherwise `null`. |
| `forwarding.matched_by` | string \| null | `domain` or `mx` on a match; otherwise `null`. |
| `blocked` | bool \| null | `true`: disposable or rejected relay. `false`: neither. `null`: relay rejection is enabled but detection is inconclusive. A positive disposable result always blocks. |

`blocked` does not replace `format` or `dns`. When enforcing relay rejection, require `blocked === false`; missing or `null` is not an allow decision.

## Premium fields

Available on Pro when requested, except `spam_trap`, which runs automatically. These are domain-configuration and reputation signals, not verification of a sent message. See [Premium Features](https://docs.disify.com/guide/premium-features.md).

| Field | Type | Description |
| --- | --- | --- |
| `email_auth.spf` | string | SPF `all`-policy summary: `pass`, `neutral`, `softfail`, `hardfail`, or `none`. This does not evaluate a sending IP. |
| `email_auth.spf_record` | string \| null | The raw SPF record, or `null` when none is found. |
| `email_auth.dmarc` | object | Always has `policy` (`reject`, `quarantine`, `none`, or `absent` when no record) and `record` (string \| null). Adds `subdomain_policy`, `pct`, `rua`, `ruf`, `adkim`, `aspf` only when those tags are present in the record. |
| `email_auth.dkim_configured` | bool | Whether DKIM records were found at the selectors DISIFY probes. Other selectors may exist. |
| `email_auth.dkim_selectors_found` | array | The DKIM selectors discovered. |
| `domain_age` | object | `registered` (date), `age_days` (int), `fresh` (bool). |
| `inbox_provider` | string | Mailbox provider name (e.g. Google Workspace, Microsoft 365). |
| `deliverability_score` | int | Score 0–100 from available authentication, MX, and domain-age inputs. It is not a delivery probability. |
| `spam_trap` | object | `is_trap` (bool), `type` (string \| null), `reason` (string \| null). Automatically included on Pro. |

## Bulk fields

Bulk requests return a different shape — see [Bulk Validation](https://docs.disify.com/api/bulk.md#bulk-response-fields).

Source: https://docs.disify.com/api/response-fields.html