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