網域驗證與 DNS 設定
使用帳戶產生的 TXT 記錄，完成寄件網域所有權驗證。
1. 新增前確認
新增需有生效套餐及可用節點。max_domains 是套餐硬上限，並非技術上的無限網域。多個網域共享目前套餐發送額度。請使用 ASCII FQDN，衝突、上限或節點問題應先排查，勿重複提交。
curl -X POST "${SMTPDOG_API_ORIGIN}/domains" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"domain_name":"example.com"}'2. 使用真實 TXT 記錄
建立回應或 GET /domains/{id} 可回傳 type、name、value。DKIM selector、公鑰與 SPF include 必須使用實際值，此頁不提供可發布的示範 TXT。DNS 業者可能需相對主機名稱；既有 SPF 須審核合併，不可盲目覆蓋或發布多筆 SPF。
| 欄位 / 設定 | 型別 / 狀態 | 說明 |
|---|---|---|
| type | string | 目前為 TXT |
| name | string | 使用完整回傳名稱，核對相對 Host 規則 |
| value | string | 使用回傳 DKIM 公鑰／SPF，不拼接示範值 |
type: TXT
name: <use the actual dns_records[].name>
value: <use the actual dns_records[].value>3. 在 DNS 解析平台新增記錄
每個寄件網域在你的帳戶裡都有專屬的 DKIM 選擇器、公鑰和 SPF 記錄。將它們作為 TXT 記錄新增到你的 DNS 解析平台，然後回到控制台點擊驗證。
- STEP 01 · 取得專屬記錄在控制台新增寄件網域
在控制台輸入要綁定的網域（根網域或子網域），系統會回傳專屬的 dns_records 清單（包含 type、name、value）。
- STEP 02 · 新增 TXT 記錄在 DNS 服務商處建立
登入你的網域解析平台，將每條記錄新增為 TXT，並注意「主機記錄」是否要求只填相對名稱。
- STEP 03 · 驗證確認 all_passed
等待解析生效後回到控制台點擊「驗證」，當 SPF 與 DKIM 檢查項目均通過（all_passed 為 true）即可寄信。
主流 DNS 解析平台填寫教學
不同平台對「主機記錄（Host / Name）」是否自動補上主網域字尾的規則不同，請選擇你的網域商：
1. 平台進入路徑
登入 Cloudflare 控制台 → 選擇你的網域 → 左側「DNS」→「記錄 (Records)」→「新增記錄 (Add record)」。
2. 主機記錄（Host / Name）怎麼填
在「名稱 (Name)」欄：根網域記錄（如 SPF）填 @，子網域填前綴（如 mail）；DKIM 填控制台回傳的相對部分 <selector>._domainkey。Cloudflare 也接受完整名稱，會自動正規化。
3. 記錄類型與記錄值怎麼填
類型選擇 TXT，將控制台產生的記錄值原樣貼到「內容 (Content)」，頭尾不要有多餘空格。
4. TTL 與生效時間
TTL 保持「自動 (Auto)」即可，TXT 記錄不經過代理。通常很快生效，但請預留幾分鐘。
1. 平台進入路徑
登入阿里雲控制台 → 雲解析 DNS →「公網權威解析」→ 找到你的網域 →「解析設置」→「添加記錄」。
2. 主機記錄（Host / Name）怎麼填
重點：「主機記錄」只填相對名稱，系統會自動補上你的主網域。控制台回傳 example.com 時填 @；回傳 mail.example.com 時只填 mail；DKIM 只填 <selector>._domainkey。
3. 記錄類型與記錄值怎麼填
「記錄類型」選擇 TXT，將完整的 SPF 或 DKIM 字串貼到「記錄值」。
4. TTL 與生效時間
「解析請求來源」保持預設，TTL 建議選 10 分鐘（600 秒），新增後等幾分鐘再驗證。
1. 平台進入路徑
登入 DNSPod 控制台 →「我的網域」→ 點擊需要寄信的網域 →「添加記錄」。
2. 主機記錄（Host / Name）怎麼填
規則與阿里雲一致：「主機記錄」只填相對名稱，根網域填 @，子網域或 DKIM 填對應前綴。不要再填一次主網域，否則會變成 example.com.example.com，驗證不會通過。
3. 記錄類型與記錄值怎麼填
記錄類型選 TXT，直接貼上控制台顯示的記錄值，不要自己再加雙引號。
4. TTL 與生效時間
線路類型選「預設」，TTL 保持預設的 600 秒，儲存後回控制台驗證。
1. 平台進入路徑
進入 Route 53 控制台 →「Hosted zones」→ 點擊目標網域 →「Create record」。
2. 主機記錄（Host / Name）怎麼填
觀察「Record name」輸入框是否已固定以你的網域結尾：若是，只填相對部分（根網域留空）。SPF 與 DKIM 分別建立為獨立的 TXT 記錄。
3. 記錄類型與記錄值怎麼填
Record type 選 TXT，貼上記錄值。若該主機名稱下已有 SPF，請把 include 合併進同一條 v=spf1 記錄。單一文字字串最長 255 個字元，若服務商拒絕較長的 DKIM 值，請在同一條記錄內把它拆成多段、每段不超過 255 個字元並各自加引號。
4. TTL 與生效時間
TTL 建議先設 300 秒（5 分鐘），等服務商同步完成後再回控制台驗證。
各服務商控制台的介面會不定期調整。若選單名稱有出入，請遵循同樣的規則：主機記錄填相對名稱、類型選 TXT、記錄值原樣貼上。
主機記錄（Host）相對名稱轉換對照表
當你的平台會自動附加主網域時，請把控制台回傳的完整記錄名轉換為「相對主機記錄」：
| 解析情境 | 控制台回傳的 name | 主機記錄填寫 | 填寫說明 |
|---|---|---|---|
| 根網域 SPF | example.com | @ | @ 代表根網域；若已有 SPF 請合併，不要新增第二條。 |
| 子網域 SPF | mail.example.com | 去掉結尾的 .example.com，只填子網域前綴。 | |
| 根網域 DKIM | <selector>._domainkey.example.com | <selector>._domainkey | 使用控制台實際回傳的 selector，去掉主網域。 |
| 子網域 DKIM | <selector>._domainkey.mail.example.com | <selector>._domainkey.mail | 保留子網域段 .mail，僅去掉結尾的 .example.com。 |
常見問題
1. 同一主機名稱只能有一條 SPF：同一主機名稱下不能存在多條 v=spf1 記錄。若你已為其他郵件服務設定過 SPF，請把控制台提供的 include 合併進原有記錄，不要新增第二條。
2. DKIM 值很長：DKIM 公鑰超過 255 個字元。多數平台會自動拆分；如果你的平台不會，請在同一條 TXT 記錄裡拆成多段、每段不超過 255 個字元並各自加引號。
3. 驗證介面回傳 HTTP 200 只代表檢查已執行完畢。請確認 all_passed 為 true；未通過時對照 checks[] 裡的 expected_value 與 found_values 排查。
4. 主動驗證與結果
POST /domains/{id}/verify 無需本文。HTTP 200 時 all_passed 仍可能是 false。逐項檢查 passed、expected_value、found_values 及 lookup_error，須全部通過。DNS 驗證不等於節點設定完成，也不是持續監測承諾。
| 欄位 / 設定 | 型別 / 狀態 | 說明 |
|---|---|---|
| all_passed / status | bool / string | 全部通過與目前狀態 |
| checks[].name | string | dkim / spf |
| record_name / expected_value / passed | string / bool | 記錄預期值與通過結果 |
| found_values / lookup_error | string[] / string | 可省略，用於 DNS 排錯 |
curl -X GET "${SMTPDOG_API_ORIGIN}/domains/${SMTPDOG_DOMAIN_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X POST "${SMTPDOG_API_ORIGIN}/domains/${SMTPDOG_DOMAIN_ID}/verify" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"5. 排查與解除綁定
TXT 不符時核對完整 name/value、DNS 生效及業者格式。目前沒有 DMARC 驗證介面。DELETE /domains/{id} 會設為 disabled 並保留歷史，不保證立即重綁或轉移帳戶。部分建立失敗請聯絡支援，避免無限重試。