CLI
@billionsend/cli 讓你在終端機裡把電子郵件服務帳號遷移到 BillionSend。
@billionsend/cli 用來把電子郵件服務帳號遷移到 BillionSend。它讀取來源帳號,與你的帳號比對,套用差異並寫出報告。目前唯一支援的來源是 Resend。逐步指南見從 Resend 遷移。套件是 npm 上的 @billionsend/cli,原始碼在 GitHub 的 billionsend/billionsend-cli。
安裝
需要 Node 18 或更新版本。不必安裝,直接執行:
npx @billionsend/cli migrate --from resend
也可以一次性安裝:
npm install -g @billionsend/cli
billionsend --version
指令
billionsend migrate --from resend # 連線、選擇資源、產生計畫、確認、套用
billionsend migrate plan --from resend [--out plan.json] # 唯讀:結束碼 0 表示無須處理,2 表示有變更,1 表示出錯
billionsend migrate apply [plan.json] [--yes] # 套用已儲存的計畫,或一次完成產生與套用
billionsend migrate status # 上一次執行建立了什麼,還剩什麼
billionsend migrate rollback [--yes] # 只刪除這個工具建立的內容
migrate是互動式路徑。它會詢問缺少的內容(金鑰),讓你選擇資源,顯示計畫,請你確認,然後套用並列印摘要。migrate plan顯示將會發生的變更,不寫入任何內容。在任何寫入之前,它會透過GET /usage檢查你方案的限額,並說明哪些放不下,例如「7 domains to create; the Free plan allows 3」。它還會估算所需時間。migrate apply套用已儲存的計畫,或一次完成產生與套用。聯絡人依電子郵件地址配對。其他一切依名稱、鍵、端點或別名配對,不同就更新,相同就保持不動。migrate status顯示上一次執行建立了什麼,以及檢查清單上還剩什麼。它不需要金鑰。migrate rollback只刪除這個工具建立的內容,絕不碰只是被它更新過的資料列。它會先列印清單並詢問(--yes可略過詢問)。
參數
| 參數 | 含義 |
|---|---|
--from <provider> |
來源服務商。目前只有 resend。 |
--from-key-stdin |
從 stdin 讀取來源 API 金鑰(第一行)。 |
--from-key <key> |
以參數形式傳入來源 API 金鑰。程序清單裡看得到,所以建議用環境變數。 |
--to-url <url> |
BillionSend API 位址。預設 https://api.billionsend.com。 |
--to-key-stdin |
從 stdin 讀取 BillionSend API 金鑰(兩個 stdin 參數都設定時為第二行)。 |
--to-key <key> |
以參數形式傳入 BillionSend API 金鑰。同樣要留意上面的問題。 |
--rps <n> |
對來源服務的每秒請求數。預設 8,最大 100。Resend 的限額是 10,並與你的正式環境傳送共用。只有在 Resend 提高了你的限額之後,才可以超過 10。 |
--only <a,b> |
只遷移這些資源。 |
--skip <a,b> |
略過這些資源。 |
--on-conflict <mode> |
對已存在的聯絡人:upsert(預設)、skip 或 error。 |
--include-sent |
把已寄出的群發以草稿匯入。預設略過。 |
--fresh-webhook-secrets |
建立新的 Webhook 簽章金鑰,而不是複製舊的。只會在報告裡顯示一次。 |
--fresh |
捨棄續傳進度,重新讀取全部內容。先前執行建立的內容會保留,所以 rollback 仍然可用。 |
--out <file> |
migrate plan:把計畫寫成 JSON。 |
--report <file> |
同時把 Markdown 報告寫到這個路徑。 |
-y、--yes |
略過確認。 |
--non-interactive |
從不提問。缺少輸入時以 1 結束。stdin 不是終端機時,以及使用 --json 時會自動啟用。 |
--json |
stdout 輸出 JSON,進度輸出到 stderr。 |
-v、--verbose |
記錄每一次請求。 |
--color <mode>、--no-color |
auto(預設)、always 或 never。 |
-h、--help / -V、--version |
說明與版本。 |
--only 與 --skip 可用的資源,依套用順序為:domains、properties、topics、segments、contacts、enrichment、broadcasts、templates、webhooks、suppressions、api-keys。enrichment 是第二輪,用來讀取每位聯絡人的訂閱主題與屬性。
環境變數
| 變數 | 含義 |
|---|---|
RESEND_API_KEY |
來源 API 金鑰,完整存取。 |
BILLIONSEND_API_KEY |
你的 BillionSend API 金鑰,完整存取。 |
BILLIONSEND_BASE_URL |
BillionSend API 位址,與 --to-url 相同。 |
NO_COLOR |
關閉顏色。 |
FORCE_COLOR |
即使經過管線也輸出顏色。 |
每把金鑰依這個順序尋找:環境變數、-stdin 參數、命令列參數,最後在終端機裡跳出隱藏輸入的提示。
檔案
工具會把這些檔案寫在你執行它的位置旁邊,只有你自己可讀,其中絕不包含金鑰:
| 檔案 | 內容 |
|---|---|
.billionsend/migrate-state.json |
工具建立了什麼、停在哪裡,這樣中斷的執行可以繼續。 |
.billionsend/migrate-report.json |
上一次執行的報告,資料格式。 |
.billionsend/migrate-report.md |
同一份報告的 Markdown 版:數量、檢查清單、每個網域的 DNS 記錄、id 對照表(來源端的訂閱主題與分群 id 對應到 BillionSend 的 id)以及手動事項。 |
目前目錄裡有 .gitignore 時,.billionsend/ 會被加進去。
安全
- 只讀取 Resend。 對 Resend 的每個請求都是
GET。寫入只送往你的 BillionSend API。 - 金鑰只留在記憶體裡,並且會從每一行日誌中隱去。沒有遙測,也不檢查更新。
- 遇到
401或403就停止。 工具不會重試,也不會繞過。 - 遵守速率限制。 遇到
429時會等待retry-after。遇到伺服器或網路錯誤時,會以逐漸加長的間隔最多重試 5 次。 - 保留退訂狀態。
unsubscribed與訂閱主題的退訂原樣複製,不會讓任何人重新訂閱。見退訂。
結束碼
| 結束碼 | 含義 |
|---|---|
0 |
成功;對 migrate plan 來說,表示無須處理。 |
1 |
錯誤:參數有誤、缺少輸入、金鑰被拒絕。 |
2 |
僅 migrate plan:計畫裡有變更。 |
3 |
部分完成:有些項目失敗。見報告。 |
腳本與 CI
stdin 不是終端機,或者使用了 --non-interactive 或 --json 時,工具從不提問。缺少輸入時以 1 結束,並指出需要設定的變數或參數。請透過環境變數或 stdin 傳入金鑰,不要當作參數傳入:
export RESEND_API_KEY=re_...
export BILLIONSEND_API_KEY=bs_...
billionsend migrate plan --from resend --out plan.json
# 結束碼 2 表示有內容需要套用
billionsend migrate apply plan.json --yes
使用 --json 時,stdout 只輸出 JSON(migrate plan 輸出計畫,migrate apply 輸出報告),可以直接接上管線:
billionsend migrate plan --from resend --json | jq '.counts'
Resend 是 Plus Five Five, Inc. 的註冊商標。BillionSend 與 Resend 無關聯,也未獲其背書。