繁中
English繁中

安全使用代理郵件

作者: /

安全使用代理郵件

代理郵件是一種命令列工具，可透過已設定為使用 Gmail 的 WordPress 網站發送訊息。每次發送都是明確的：來電者會提供收件人、主旨和主體。該工具不會監控信箱或自動發送訊息。

WordPress 保留 Gmail 授權並強制管理員管理的收件人允許清單。CLI 使用獨立的代理郵件金鑰;它不需要 Gmail 憑證或 Bugzilla API 金鑰。

第一次發送前

WordPress 管理員必須：

  • 連結該網站的 Gmail 帳號。
  • 在網站的代理郵件設定中啟用代理郵件端點。
  • 將預定收件人地址加入允許清單。
  • 提供端點網址及專用代理郵件金鑰給授權營運者。

端點必須使用 HTTPS。從 WordPress 設定複製完整網址，而不是猜測路由。

CLI 需要 Node.js 18 或更新版本。如果你有核准的原始碼檢查，先從根執行 npm link 一次，然後確認是否 agent-mail --help 可行。

設定 CLI

設定兩個值：WordPress 中顯示的完整 HTTPS 端點，以及專用的代理郵件金鑰。在 Windows 上，使用者層級的設定檔為：

%APPDATA%\bugzilla-cli\.env.agent-mail.local

在 macOS 或 Linux 上，使用，或~/.config/bugzilla-cli/.env.agent-mail.local是$XDG_CONFIG_HOME/bugzilla-cli/.env.agent-mail.local當 XDG_CONFIG_HOME 是取消設定。

檔案中包含這些佔位符;在本地替換它們，且永遠不會發布真實值：

WMP_MAIL_URL=https://your-wordpress.example/wp-json/<agent-mail-endpoint>
WMP_MAIL_KEY=your-dedicated-agent-mail-key

CLI 先讀取使用者層級檔案，接著讀取當前目錄中的可選 .env.agent-mail.local 檔案，接著處理環境變數。後續值會覆蓋先前的值。這些設定與 Bugzilla CLI 設定是分開的。

組態檔案以純文字形式儲存金鑰。限制對檔案的存取，避免專案本地副本被版本控制，並避免將金鑰放在殼層歷史或命令列參數中。你可以改用程序環境變數來執行短命的會話。

準備訊息

建立一個包含 to、 subject和 body 字串的 UTF-8 JSON 檔案。收件人必須與 WordPress 允許清單上的地址相符。

{
  "to": "[email protected]",
  "subject": "Project update",
  "body": "Hello, here is the update.",
  "attachments": ["./report.pdf"]
}

當訊息中沒有檔案時，則省略 attachments 。執行 CLI 的電腦讀取附件路徑;WordPress 會接收每個檔名和檔案內容，而非本地路徑。

發送一次

從包含 message.json的目錄執行：

agent-mail send --data '@message.json'

該指令會提交一則訊息。成功回應時會包含 Gmail message_id。這確認 Gmail 已接受該請求;但不會確認收件匣已送達。

如果指令逾時或報告伺服器錯誤，送達可能會不確定。在決定是否再次發送前，請先檢查 Gmail 帳號的已發送資料夾。CLI 不會自動重試。

限制與故障排除

  • 支援一個允許列出的收件人及一個純文字正文。不支援 HTML 郵件、多重收件人、抄送及密件副本。
  • 主體最多可達 200 UTF-8 位元組;主體可達 40,000 位元組。
  • 最多可附加五個一般檔案，解碼後的總大小為 10 MiB。
  • 回應 403 通常表示端點被停用、金鑰無效，或收件人未被允許名單。請 WordPress 管理員檢查代理郵件設定。
  • 驗證錯誤表示 JSON 欄位或附件清單未符合上述限制。
  • 若逾時或伺服器錯誤不確定，請先檢查 Gmail 已發送後再嘗試。

將代理郵件金鑰視為憑證。如果可能已被暴露，請 WordPress 管理員更換並更新本地設定。

返回頂端