身份验证
请将 API 密钥作为 bearer 令牌发送。该密钥必须具有 mail.view 权限；缺少该权限的密钥将被拒绝并返回 403 状态码，而非 404。
您的组织 ID 应填在此处
此端点将 org_id 作为查询参数。不填则调用涵盖您的整个租户子树；发送该参数则将调用范围缩小到一个组织。
您的组织ID位于控制面板的API密钥屏幕上，就在密钥本身的旁边。这是您在每次调用时使用的相同ID。
免费试用
将尖括号中的内容替换为您自己的值，并将键占位符替换为您仪表板中的一个键。
curl -X GET https://api.zinndigital.com/v1/mail/preflight?fqdn=<fqdn> \
-H "Authorization: Bearer zdk_live_…"已登录？您仪表板中的 API 控制台会自动填入您真实的组织 ID 和您自己的密钥，并针对实时 API 运行请求，以便您查看实际的响应。 在 API 控制台中打开此端点
详细信息
Read-only. Answers **before the customer commits** whether this domain can take our mail records, and exactly what publishing them would remove (#662). Setting mail up rewrites the domain's apex `MX`. If the domain already receives email somewhere else, that stops inbound mail reaching the mailboxes it is addressed to — an outage the customer usually learns about from the people who could not reach them. Without this endpoint the only way to discover the refusal was to create a service and watch it fail asynchronously, which is a refusal arriving *after* the decision. `safe: false` means `POST /v1/mail/services` will refuse unless it is called with the override flag. `foreign_mx` and `would_delete` are listed **verbatim**, not counted, because a customer must be able to see what they are about to destroy before confirming it. `zone_unreadable: true` is **never** `safe`: there is no DNS resolver in the platform, so "we could not read the zone" is the normal answer for a domain whose DNS is hosted elsewhere, and treating that as safe would disable the guard exactly where it matters most. ⚠️ A safe answer is not a promise — the zone can change between this call and the apply, so provisioning repeats the check inside its workflow. Requires `mail.view`.
参数
| 名称 | 类型 | 必填 | 内容简介 |
|---|---|---|---|
fqdn (query) | string | 是 | The domain to check. |
provider (query) | MailProvider | 否 | Which provider's records to test against; defaults to our own mail. The answer differs per provider, because each preset publishes a different record set. |
mx_hosts (query) | string | 否 | `custom` only: the MX targets the reseller has typed so far, comma-separated. The preflight compares the zone with the records the preset **would** publish, and for a provider w… |
org_id (query) | Uuid | 否 | The organization to act in; defaults to the caller's own when unambiguous. |
响应
| 名称 | 类型 | 必填 | 内容简介 |
|---|---|---|---|
domain | string | 是 | The domain that was checked, normalised. |
safe | boolean | 是 | Whether an apply would proceed without the override flag. `false` means `POST /v1/mail/services` returns 409 unless the customer confirms. |
existing_apex_mx | string[] | 是 | Every apex `MX` currently published, in the order DNS returned them. |
foreign_mx | string[] | 是 | The apex `MX` targets that are not ours to replace — the reason for a refusal, and the list the customer must see before confirming an override. |
foreign_spf_includes | string[] | 是 | `include:` mechanisms in the current SPF that the new record would drop. |
would_delete | string[] | 是 | Records the apply would remove or replace, as `"NAME TYPE VALUE"`. |
zone_unreadable | boolean | 是 | The zone could not be read at all — never `safe`. Distinct from "read it, found nothing", because the two need different copy: one is "we cannot see your DNS", the other is "you… |
reason | string | 是 | Customer-grade English describing what was found. Empty when safe. |
warnings | string[] | 是 | Non-blocking observations about the zone. |
此端点可能返回的错误
401 · 403 · 422 · 429 · 503