量檢測：接口參數(shù)、返回字段與工程接入要點)
為什么要在業(yè)務(wù)里單獨做一次郵箱檢測用戶準備、活動報名、郵件訂閱這類流程中郵箱是賬號恢復(fù)、通知觸達和身份確認的重要載體。一個看似合法的郵箱地址可能在格式上通過校驗但實際域不存在 MX 記錄或者來自臨時郵箱域名。若不在入口處攔截后續(xù)會帶來大量無法送達的郵件、虛假賬號和風控維護復(fù)雜度。郵箱地址檢測接口把多個維度的判斷合并成一次 HTTP 請求返回統(tǒng)一的評分和原因清單適合嵌入到準備表單提交、批量名單清洗、KYC 輔助核驗等環(huán)節(jié)。本文記錄這個接口的接入?yún)?shù)、返回結(jié)構(gòu)和工程落地時的注意事項供后端開發(fā)同學參考。接口能力邊界在寫代碼之前先明確這個接口能做什么、不能做什么避免誤用。一次請求完成 6 項檢測RFC 5322 格式校驗判斷郵箱整體結(jié)構(gòu)是否符合規(guī)范。臨時/一次性郵箱檢測基于 72,345 條開源域名庫、3 個數(shù)據(jù)源合并去重后的結(jié)果進行比對。MX 記錄驗證通過 AliDNS DoH 查詢域名 MX 記錄不依賴服務(wù)器本地的 getmxrr 函數(shù)結(jié)果更穩(wěn)定。拼寫糾正對常見域名拼寫錯誤給出建議例如gmial.com提示為gmail.com。服務(wù)商識別識別 QQ 郵箱、Gmail、網(wǎng)易、Outlook 等 40 主流郵箱服務(wù)商。綜合風險評分輸出 0-100 的風險分數(shù)并附帶詳細原因清單。接口的 QPS 配額為 10 / s郵箱地址最長支持 254 字符RFC 上限。需要說明的是接口返回的是單一時間點的檢測結(jié)果不保證域名后續(xù)新增或刪除 MX 記錄會實時反映域名庫的更新頻率以文檔為準。請求參數(shù)與鑒權(quán)Query 參數(shù)參數(shù)名類型必填說明emailstring是要檢測的郵箱地址最長 254 字符Header 參數(shù)參數(shù)名類型必填說明X-API-Keystring否API Key不傳時走匿名額度接口為 GET 請求地址為https://v1.apizero.cn/api/email-check。匿名額度不要求攜帶X-API-Key但在高并發(fā)或生產(chǎn)環(huán)境建議申請獨立的 API Key 使用具體申請方式以文檔為準。curl 接入示例先通過 curl 驗證接口連通性替換$APIZERO_API_KEY為你的實際 Key將email替換為目標郵箱curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/email-check?emailemail如果不帶 Key直接去掉 Header 即可curl -sS \ https://v1.apizero.cn/api/email-check?emailtestgmial.com上述命令返回 JSON 數(shù)組其中code為 0 時表示請求成功。注意響應(yīng)是一個數(shù)組結(jié)構(gòu)即使只返回一個元素也需要按數(shù)組解析。Python 代碼接入示例在實際業(yè)務(wù)中通常不在命令行里調(diào)用而是封裝成一個服務(wù)函數(shù)。以下是一個基于requests庫的接入示例import requests API_ENDPOINT https://v1.apizero.cn/api/email-check API_KEY your-api-key-here # 不傳則走匿名額度 def check_email(email: str, timeout: float 5.0) - dict: headers {} if API_KEY: headers[X-API-Key] API_KEY params {email: email} resp requests.get(API_ENDPOINT, paramsparams, headersheaders, timeouttimeout) resp.raise_for_status() # 接口返回 JSON 數(shù)組取第一個元素 body resp.json() if not isinstance(body, list) or len(body) 0: raise ValueError(unexpected response format) item body[0] if item.get(status) ! 200 or item.get(code) ! 0: raise RuntimeError(api error: {}.format(item)) return item[data] if __name__ __main__: result check_email(testgmial.com) print(risk_score:, result[risk_score]) print(risk_level:, result[risk_level]) print(reasons:) for reason in result[reasons]: print( -, reason)這段代碼做了三件必要的事設(shè)置超時、通過raise_for_status()暴露 HTTP 層錯誤、校驗響應(yīng)結(jié)構(gòu)后再取數(shù)據(jù)。生產(chǎn)環(huán)境中建議把API_KEY放到環(huán)境變量或密鑰管理服務(wù)中不要硬編碼在代碼倉庫里。返回字段解讀以素材中的testgmial.com為例成功響應(yīng)中data部分包含以下關(guān)鍵字段字段名類型說明emailstring原始郵箱地址inputstring用戶輸入值localstring郵箱地址的本地部分domainstring郵箱地址的域名部分valid_formatbool是否符合 RFC 5322 格式has_mxbool域名是否存在 MX 記錄mx_recordsarrayMX 記錄列表無記錄時為空數(shù)組is_disposablebool是否屬于臨時/一次性郵箱域名disposable_matchstring/null命中的臨時郵箱域名記錄來源providerstring/null識別的郵箱服務(wù)商名稱is_trustedbool是否屬于可信域名spelling_suggestionstring/null拼寫糾正建議risk_scoreint綜合風險評分0-100risk_levelstring風險等級例如invalidreasonsarray[string]風險原因清單data 外層還有code、msg、request_id三個字段。request_id在排查問題時非常有用建議在日志中記錄。在示例中risk_score為 5risk_level為invalid原因是域名無 MX 記錄、域名疑似拼寫錯誤、本地部分含測試/系統(tǒng)類關(guān)鍵詞。這說明風險評分不是只看單一維度而是綜合了格式、域名可接收性、臨時郵箱庫和歷史經(jīng)驗等多方面信息。幾個容易誤解的字段is_disposable: false并不代表郵箱一定安全還需要結(jié)合has_mx和risk_score綜合判斷。provider: null表示接口未能識別域名屬于哪家服務(wù)商可能是小眾域名或拼寫錯誤域名。spelling_suggestion只在識別出疑似拼寫錯誤時返回正常域名下為null。常見錯誤與排查思路接入過程中遇到問題按照以下層次排查效率更高。1. HTTP 層異常400 Bad Requestemail參數(shù)缺失或超過 254 字符檢查 URL 編碼是否正確。401 UnauthorizedX-API-Key無效或已過期確認 Key 是否復(fù)制完整。429 Too Many Requests請求頻率超過 10 QPS 配額需要降速或聯(lián)系調(diào)整配額。2. 響應(yīng)結(jié)構(gòu)與狀態(tài)碼不一致接口返回 HTTP 200 時業(yè)務(wù)層面的code字段仍然可能表示失敗。不能只判斷 HTTP 狀態(tài)碼還要檢查code和status。建議在代碼中統(tǒng)一斷言item[status] 200 and item[code] 0。3. DNS 與 MX 查詢的時延波動MX 記錄驗證依賴 DNS 查詢極端情況下可能使整體接口耗時拉長。客戶端設(shè)置 5 秒超時是一個相對穩(wěn)妥的起點如果業(yè)務(wù)鏈路對耗時敏感可以加入緩存策略見下文。4. 郵箱地址的特殊字符部分郵箱地址包含、-、_等字符例如usertagexample.com。在拼接 URL 時務(wù)必使用params字典或urlencode處理不要手動拼接字符串避免被解析為空格。工程化注意事項超時與重試網(wǎng)絡(luò)請求必須設(shè)置超時并按業(yè)務(wù)容忍度配置重試。建議采用指數(shù)退避策略第一次失敗后等待 1 秒、第二次 2 秒、第三次 4 秒最多重試 2 次。對于用戶準備場景可以在前端先做一次本地格式校驗再把完整檢測放到后端異步執(zhí)行避免同步阻塞表單提交。緩存設(shè)計同一郵箱在短時間內(nèi)被重復(fù)檢測的場景很常見?？梢园脆]箱地址做本地緩存TTL 設(shè)為 10-30 分鐘降低接口調(diào)用量。需要注意MX 記錄和臨時郵箱域名庫會變化緩存時間不宜過長。如果業(yè)務(wù)對準確性要求極高可以不緩存risk_score只緩存valid_format等幾乎不會變化的字段。批量場景的速率控制接口 QPS 為 10 / s批量清洗郵件列表時不能一次性并發(fā)發(fā)出大量請求。建議在本地做令牌桶限流控制請求速率在 8 QPS 左右留出余量。同時記錄每個request_id方便對賬。日志與監(jiān)控至少記錄以下信息調(diào)用時間、目標郵箱、接口耗時HTTP 狀態(tài)碼、業(yè)務(wù) code、request_id返回的 risk_score 和 risk_level異常類型和重試次數(shù)這些數(shù)據(jù)接入監(jiān)控后可以及時發(fā)現(xiàn)接口調(diào)用異?；驑I(yè)務(wù)異常波動例如某個時間段risk_score平均值突然升高可能意味著臨時郵箱域名庫更新或被攻擊者利用。不要做的事不要把接口返回的risk_score直接作為唯一決策依據(jù)建議結(jié)合業(yè)務(wù)規(guī)則如黑名單、準備頻次綜合判斷。不要用reasons數(shù)組的中文文案直接展示給終端用戶這些內(nèi)容更適合在后臺風控日志里查看。不要忽略匿名額度的限制生產(chǎn)環(huán)境請使用正式 API Key。小結(jié)郵箱地址檢測接口把格式校驗、臨時郵箱識別、MX 驗證、拼寫糾正、服務(wù)商識別和風險評分打包成一個簡單 GET 請求降低了風控邏輯的重復(fù)開發(fā)維護復(fù)雜度。接入時重點關(guān)注響應(yīng)數(shù)組結(jié)構(gòu)、業(yè)務(wù)碼判斷、超時重試和速率限制即可穩(wěn)定嵌入到準備、營銷、KYC 等場景中。參考文檔接口文檔https://apizero.cn/aidocs/email-check原始文檔https://apizero.cn/aidocs/email-check/raw.md 準備場景下的郵箱質(zhì)量檢測：接口參數(shù)、返回字段與工程接入要點
為什么要在業(yè)務(wù)里單獨做一次郵箱檢測用戶準備、活動報名、郵件訂閱這類流程中郵箱是賬號恢復(fù)、通知觸達和身份確認的重要載體。一個看似合法的郵箱地址可能在格式上通過校驗但實際域不存在 MX 記錄或者來自臨時郵箱域名。若不在入口處攔截后續(xù)會帶來大量無法送達的郵件、虛假賬號和風控維護復(fù)雜度。郵箱地址檢測接口把多個維度的判斷合并成一次 HTTP 請求返回統(tǒng)一的評分和原因清單適合嵌入到準備表單提交、批量名單清洗、KYC 輔助核驗等環(huán)節(jié)。本文記錄這個接口的接入?yún)?shù)、返回結(jié)構(gòu)和工程落地時的注意事項供后端開發(fā)同學參考。接口能力邊界在寫代碼之前先明確這個接口能做什么、不能做什么避免誤用。一次請求完成 6 項檢測RFC 5322 格式校驗判斷郵箱整體結(jié)構(gòu)是否符合規(guī)范。臨時/一次性郵箱檢測基于 72,345 條開源域名庫、3 個數(shù)據(jù)源合并去重后的結(jié)果進行比對。MX 記錄驗證通過 AliDNS DoH 查詢域名 MX 記錄不依賴服務(wù)器本地的 getmxrr 函數(shù)結(jié)果更穩(wěn)定。拼寫糾正對常見域名拼寫錯誤給出建議例如gmial.com提示為gmail.com。服務(wù)商識別識別 QQ 郵箱、Gmail、網(wǎng)易、Outlook 等 40 主流郵箱服務(wù)商。綜合風險評分輸出 0-100 的風險分數(shù)并附帶詳細原因清單。接口的 QPS 配額為 10 / s郵箱地址最長支持 254 字符RFC 上限。需要說明的是接口返回的是單一時間點的檢測結(jié)果不保證域名后續(xù)新增或刪除 MX 記錄會實時反映域名庫的更新頻率以文檔為準。請求參數(shù)與鑒權(quán)Query 參數(shù)參數(shù)名類型必填說明emailstring是要檢測的郵箱地址最長 254 字符Header 參數(shù)參數(shù)名類型必填說明X-API-Keystring否API Key不傳時走匿名額度接口為 GET 請求地址為https://v1.apizero.cn/api/email-check。匿名額度不要求攜帶X-API-Key但在高并發(fā)或生產(chǎn)環(huán)境建議申請獨立的 API Key 使用具體申請方式以文檔為準。curl 接入示例先通過 curl 驗證接口連通性替換$APIZERO_API_KEY為你的實際 Key將email替換為目標郵箱curl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/email-check?emailemail如果不帶 Key直接去掉 Header 即可curl -sS \ https://v1.apizero.cn/api/email-check?emailtestgmial.com上述命令返回 JSON 數(shù)組其中code為 0 時表示請求成功。注意響應(yīng)是一個數(shù)組結(jié)構(gòu)即使只返回一個元素也需要按數(shù)組解析。Python 代碼接入示例在實際業(yè)務(wù)中通常不在命令行里調(diào)用而是封裝成一個服務(wù)函數(shù)。以下是一個基于requests庫的接入示例import requests API_ENDPOINT https://v1.apizero.cn/api/email-check API_KEY your-api-key-here # 不傳則走匿名額度 def check_email(email: str, timeout: float 5.0) - dict: headers {} if API_KEY: headers[X-API-Key] API_KEY params {email: email} resp requests.get(API_ENDPOINT, paramsparams, headersheaders, timeouttimeout) resp.raise_for_status() # 接口返回 JSON 數(shù)組取第一個元素 body resp.json() if not isinstance(body, list) or len(body) 0: raise ValueError(unexpected response format) item body[0] if item.get(status) ! 200 or item.get(code) ! 0: raise RuntimeError(api error: {}.format(item)) return item[data] if __name__ __main__: result check_email(testgmial.com) print(risk_score:, result[risk_score]) print(risk_level:, result[risk_level]) print(reasons:) for reason in result[reasons]: print( -, reason)這段代碼做了三件必要的事設(shè)置超時、通過raise_for_status()暴露 HTTP 層錯誤、校驗響應(yīng)結(jié)構(gòu)后再取數(shù)據(jù)。生產(chǎn)環(huán)境中建議把API_KEY放到環(huán)境變量或密鑰管理服務(wù)中不要硬編碼在代碼倉庫里。返回字段解讀以素材中的testgmial.com為例成功響應(yīng)中data部分包含以下關(guān)鍵字段字段名類型說明emailstring原始郵箱地址inputstring用戶輸入值localstring郵箱地址的本地部分domainstring郵箱地址的域名部分valid_formatbool是否符合 RFC 5322 格式has_mxbool域名是否存在 MX 記錄mx_recordsarrayMX 記錄列表無記錄時為空數(shù)組is_disposablebool是否屬于臨時/一次性郵箱域名disposable_matchstring/null命中的臨時郵箱域名記錄來源providerstring/null識別的郵箱服務(wù)商名稱is_trustedbool是否屬于可信域名spelling_suggestionstring/null拼寫糾正建議risk_scoreint綜合風險評分0-100risk_levelstring風險等級例如invalidreasonsarray[string]風險原因清單data 外層還有code、msg、request_id三個字段。request_id在排查問題時非常有用建議在日志中記錄。在示例中risk_score為 5risk_level為invalid原因是域名無 MX 記錄、域名疑似拼寫錯誤、本地部分含測試/系統(tǒng)類關(guān)鍵詞。這說明風險評分不是只看單一維度而是綜合了格式、域名可接收性、臨時郵箱庫和歷史經(jīng)驗等多方面信息。幾個容易誤解的字段is_disposable: false并不代表郵箱一定安全還需要結(jié)合has_mx和risk_score綜合判斷。provider: null表示接口未能識別域名屬于哪家服務(wù)商可能是小眾域名或拼寫錯誤域名。spelling_suggestion只在識別出疑似拼寫錯誤時返回正常域名下為null。常見錯誤與排查思路接入過程中遇到問題按照以下層次排查效率更高。1. HTTP 層異常400 Bad Requestemail參數(shù)缺失或超過 254 字符檢查 URL 編碼是否正確。401 UnauthorizedX-API-Key無效或已過期確認 Key 是否復(fù)制完整。429 Too Many Requests請求頻率超過 10 QPS 配額需要降速或聯(lián)系調(diào)整配額。2. 響應(yīng)結(jié)構(gòu)與狀態(tài)碼不一致接口返回 HTTP 200 時業(yè)務(wù)層面的code字段仍然可能表示失敗。不能只判斷 HTTP 狀態(tài)碼還要檢查code和status。建議在代碼中統(tǒng)一斷言item[status] 200 and item[code] 0。3. DNS 與 MX 查詢的時延波動MX 記錄驗證依賴 DNS 查詢極端情況下可能使整體接口耗時拉長。客戶端設(shè)置 5 秒超時是一個相對穩(wěn)妥的起點如果業(yè)務(wù)鏈路對耗時敏感可以加入緩存策略見下文。4. 郵箱地址的特殊字符部分郵箱地址包含、-、_等字符例如usertagexample.com。在拼接 URL 時務(wù)必使用params字典或urlencode處理不要手動拼接字符串避免被解析為空格。工程化注意事項超時與重試網(wǎng)絡(luò)請求必須設(shè)置超時并按業(yè)務(wù)容忍度配置重試。建議采用指數(shù)退避策略第一次失敗后等待 1 秒、第二次 2 秒、第三次 4 秒最多重試 2 次。對于用戶準備場景可以在前端先做一次本地格式校驗再把完整檢測放到后端異步執(zhí)行避免同步阻塞表單提交。緩存設(shè)計同一郵箱在短時間內(nèi)被重復(fù)檢測的場景很常見?？梢园脆]箱地址做本地緩存TTL 設(shè)為 10-30 分鐘降低接口調(diào)用量。需要注意MX 記錄和臨時郵箱域名庫會變化緩存時間不宜過長。如果業(yè)務(wù)對準確性要求極高可以不緩存risk_score只緩存valid_format等幾乎不會變化的字段。批量場景的速率控制接口 QPS 為 10 / s批量清洗郵件列表時不能一次性并發(fā)發(fā)出大量請求。建議在本地做令牌桶限流控制請求速率在 8 QPS 左右留出余量。同時記錄每個request_id方便對賬。日志與監(jiān)控至少記錄以下信息調(diào)用時間、目標郵箱、接口耗時HTTP 狀態(tài)碼、業(yè)務(wù) code、request_id返回的 risk_score 和 risk_level異常類型和重試次數(shù)這些數(shù)據(jù)接入監(jiān)控后可以及時發(fā)現(xiàn)接口調(diào)用異?；驑I(yè)務(wù)異常波動例如某個時間段risk_score平均值突然升高可能意味著臨時郵箱域名庫更新或被攻擊者利用。不要做的事不要把接口返回的risk_score直接作為唯一決策依據(jù)建議結(jié)合業(yè)務(wù)規(guī)則如黑名單、準備頻次綜合判斷。不要用reasons數(shù)組的中文文案直接展示給終端用戶這些內(nèi)容更適合在后臺風控日志里查看。不要忽略匿名額度的限制生產(chǎn)環(huán)境請使用正式 API Key。小結(jié)郵箱地址檢測接口把格式校驗、臨時郵箱識別、MX 驗證、拼寫糾正、服務(wù)商識別和風險評分打包成一個簡單 GET 請求降低了風控邏輯的重復(fù)開發(fā)維護復(fù)雜度。接入時重點關(guān)注響應(yīng)數(shù)組結(jié)構(gòu)、業(yè)務(wù)碼判斷、超時重試和速率限制即可穩(wěn)定嵌入到準備、營銷、KYC 等場景中。參考文檔接口文檔https://apizero.cn/aidocs/email-check原始文檔https://apizero.cn/aidocs/email-check/raw.md