建立企業帳號與隔離名單
以 TENANT_ADMINS_JSON 設定獨立帳號；業務登入後只能看到自己的聯盟名單、郵件及紀錄。
BSGAI AUTOMATED MAIL SYSTEM
郵件自動化管理中心 ✦
管理全球聯絡名單、建立郵件活動，將每一次訊息準確地傳送到對的收件人。
WELCOME TO BSGAI MAIL · V1.7
今天要寄信？跟著四個步驟就能開始
每個步驟都有直接入口；正式寄送前，請先確認郵件服務連線並發送管理員測試信。
有效訂閱名單
—
已同意接收通知的聯絡人
已接受寄送
—
郵件服務商已接受，不代表收件匣送達
排程／寄送中
—
每分鐘自動檢查待寄郵件
取消訂閱名單
—
平台自動排除禁止寄送對象
近期寄送活動
最新建立的郵件與預約排程
尚無資料
快速操作
常用功能快速入口
EMAIL CAMPAIGN STUDIO
撰寫與自動排程
設計郵件主旨與內容，確認後可立即寄送或指定時間發送。
郵件即時預覽
依照目前輸入內容模擬實際郵件
BSGAI GLOBAL · OFFICIAL MAIL
郵件主旨將顯示於此
請在左側輸入郵件內容，即可即時檢視。
寄送安全設計
不會一次將所有收件人放在「收件者」或副本欄位，系統逐封個別寄送，並略過已取消訂閱者。
OPT-IN AUDIENCE MANAGEMENT
訂閱名單管理
可匯入已授權聯絡人。無論何時取消訂閱，系統都會自動阻止再次寄送。
新增與匯入聯絡人
CSV 格式：email,name,segment,locale（每批最多 200 筆）
聯絡人清單
含有效、待確認與取消訂閱狀態
尚無聯絡人
CAMPAIGN ACTIVITY
寄送活動管理
追蹤草稿、待排程、寄送中與已完成的郵件活動。
全部郵件活動
活動建立時會依群組鎖定有效名單；正式寄出時仍會檢查取消訂閱狀態。
尚無活動
PARTNERSHIP INBOX · V1.7
合作洽詢管理
官網提交的合作意願會安全儲存於後台。每個聯盟管理員只能查看自己的洽詢。
網站合作申請紀錄
依建立時間由近至遠，請由授權人員處理，切勿公開聯絡資訊。
選擇此頁面以載入詢問紀錄
填表不等於核准合作，也不會自動訂閱電子報。回覆請透過貴公司正式郵件信箱進行。
DELIVERY AUDIT LOG
郵件寄送紀錄
查看郵件服務 API 接受狀態與失敗紀錄。已接受、送達、退信與投訴是不同狀態；送達資料須啟用郵件服務商 Webhook。
最近 300 筆寄送紀錄
包含測試信、確認歡迎信與活動發送
尚無寄送紀錄
SYSTEM & AUTOMATION
自動化與系統設定
管理新訂閱歡迎通知與檢查正式寄信所需的網路環境。
寄件服務狀態
設定資料不會顯示機密 API 金鑰
寄送服務 API檢查中
寄件身分—
管理員信箱—
自動執行時間每分鐘檢查（UTC 排程）
系統版本BSGAI AUTO MAIL V1.7
排程健康檢查尚未檢查
最後自動執行時間—
待人工查核活動—
未設定伺服器或離線展示時無法確認實際排程。
部署提醒
需在 Netlify 設定環境變數：管理員信箱、加密密碼、工作階段密鑰、Resend API Key、已驗證網域寄件地址、寄件單位實體通訊地址及正式網站網址。只有發佈正式網站後，排程才會自動運作。
Netlify 排程官方文件 ↗PARTNER API · EVENT AUTOMATION
企業 API 與自動通知
支援四大聯盟及授權加盟企業以後端 API 接入；每家企業只能對自己的已確認訂閱者觸發固定通知。
⇆ BSGAI GLOBAL API HUB
合作企業以 API Key 授權接入
所有金鑰只保存在企業伺服器、Netlify 環境變數或密鑰管理服務；不要放到瀏覽器、HTML、GitHub 公開倉庫。
目前登入權限展示／未登入企業金鑰由平台管理員在部署環境配置
建立 API Key
用 node scripts/create-api-key.mjs 產生亂數金鑰及雜湊。只將雜湊設定於 PARTNER_API_CLIENTS_JSON。
雙重確認訂閱
企業呼叫 POST /partner-api?action=subscribe-request；只有收件者親自確認才成為有效名單。
自動發信事件
POST /partner-api?action=trigger，事件類型：申請收到、審核結果、活動提醒、會員歡迎。必須含唯一 eventId。
十種語言自動選取
會員名單儲存偏好語言，固定事件通知會套用繁中、英、日、韓、西、法、德、葡、印尼或越文的版本。
寄送配額與錯誤處理
企業 API 有初始每小時配額，服務端仍會檢查同意及退訂狀態；詳細 API 範例及安全檢查見 ZIP 技術文件。
可對接的流程
不用提供客戶名單給其他企業，跨站只交換已授權的事件和必要資料
GBA · 工商產品申請收到 → 審核通知 → 會員資訊
HWA · 健康活動報名 → 活動提醒 → 公告
SGREA · 房地產諮詢申請 → 受理通知 → 追蹤
SGAA · 藝術展覽報名 → 展覽提醒 → 會員資訊
注意：這些屬於既定通知流程，不包含無限制的任意收件者寄信或跨企業名單讀取。
DELIVERABILITY MONITORING
寄達分析與風險監控
區分「寄件服務商接受」和「實際投遞回報」，並避免對退信與投訴地址再次寄送。
郵件 API 已接受
0
不代表已送達
已送達（Webhook）
0
由服務商事件回報
退信
0
相關地址自動抑制
投訴
0
相關地址自動抑制
服務商 Webhook 狀態
設定 RESEND_WEBHOOK_SECRET 並在 Resend 登記正式站點 /resend-webhook
Webhook 資料可能延後、重送或缺漏；報表以收到的事件次數為準，不是獨立觸達人數，也不是開信率。郵件服務商發回簽章驗證後才會記錄。
ADMIN HELP CENTER · V1.7
使用說明與管理教學
第一次登入、建立名單、寄出測試郵件、預約自動寄送，以及錯誤排查，一次完成。
快速開始 · START HERE
第一次啟用：照著 6 個步驟完成
先確認正式網站已設定寄信服務，接著建立經同意的訂閱名單，測試成功後再發送活動郵件。切勿直接上傳未經同意的名單。
目前系統檢查展示模式／尚未檢查寄件地址：尚未檢查網站網址：尚未檢查
登入管理後台
使用管理員信箱及密碼登入。正式上線前先於 Netlify 設定 ADMIN_EMAIL、加密密碼雜湊與 SESSION_SECRET。
設定寄件信箱與網域
在 Resend 驗證公司網域，於 Netlify 環境變數設定 API 金鑰、寄件地址、正式網址及公司實體通訊地址。這些金鑰不要放在前端網頁。
網域驗證指引 ↗匯入有效訂閱名單
至「訂閱名單管理」輸入單筆或匯入 CSV，選擇所屬聯盟群組。只匯入已取得明確同意的地址，退訂者不會被重新加入。
撰寫郵件、套用範本
從「撰寫／排程郵件」選擇聯盟、填寫主旨與內文。可套用電子報、活動邀請等範本，並使用 {{name}}、{{email}}。
先發送管理員測試信
按「發送測試信至管理員」，查看實際信件外觀、文字、連結及垃圾郵件狀態。測試信只會送至設定的管理員地址。
確認人數並啟動排程
選立即寄送、儲存草稿或指定時間。建立活動時鎖定目前有效收件人，按「寄送活動管理」查看狀態與取消未寄出的部分。
常見問題與故障排除
依照實際情況展開檢查
為什麼「展示模式」不能寄出真正郵件？
展示預覽是離線模擬介面，不連接郵件 API、資料庫或排程。必須將完整原始碼以 Netlify 正式 Production 方式部署，且完成後端環境變數設定。
為什麼郵件服務顯示「尚未設定」？
請檢查 RESEND_API_KEY、RESEND_FROM_EMAIL、PUBLIC_BASE_URL 與 BUSINESS_POSTAL_ADDRESS。寄件網域須於郵件服務商完成驗證，設定後重新部署正式環境。
名單匯入後，為何實際收件人比較少？
平台只向當時有效且分類相符的訂閱者寄送。未驗證、已退訂、無效或重複的信箱不會被計入。活動開始後的退訂也會被略過。
排程沒有發送／寄送很慢？
檢查是否部署 Production、Netlify Scheduled Functions 是否執行、郵件 API 額度及環境變數。系統依批次逐封寄出，非立即全部送達；排程及批次可受執行延遲或服務商限額影響。
「已接受寄送」就是客戶已經收到信嗎？
不是。這只是郵件服務商接受寄送請求，不代表已成功送達收件匣。V1.3 已加入 Resend Webhook 接收與停寄機制；須設定正確簽章密鑰與 webhook 訂閱事件後才會顯示送達、退信與投訴。
如何在 BSGAI 與四大聯盟間分開寄送？
匯入名單時選擇 BSGAI、GBA、HWA、SGREA 或 SGAA。撰寫郵件時再選對應群組，預估有效人數會自動更新；選「全部」則涵蓋所有群組。V1.3 每位聯絡人屬於一個群組。
是否可以向購買名單、網路蒐集的信箱發信？
不建議，也不應以此平台向未經同意的人發送行銷郵件。請保存訂閱來源、同意證明、寄件單位資訊，並遵守適用的隱私與反垃圾郵件規範。
CSV 範例與群組代碼
欄位：email,name,segment
email,name,segment
member@example.com,王先生,gba
partner@example.com,Jane,hwa
member@example.com,王先生,gba
partner@example.com,Jane,hwa
允許代碼：general、bsgai、gba、hwa、sgrea、sgaa。建議以 UTF-8 儲存，Excel 開啟時也請注意編碼。
管理者寄信前自查清單
每次大量寄送之前重新檢查
V1.3 新功能操作注意
分權管理、多語版、企業 API、寄達回報
聯盟管理員登入須由總管理員先建立雜湊密碼及所屬 tenantId；不得跨聯盟查詢或發送
十語郵件在編輯器上方切換語言版本，儲存後會依會員 locale 選用；未填的語言使用預設文案
Webhook在 Resend 設定簽章密鑰、事件類型及正式回呼網址，缺少設定不顯示真實送達量
企業 API金鑰只能用在後端，不能交由網站前端或客戶端 JavaScript 發送
技術手冊與安裝步驟也保留在 ZIP 的 README_使用說明.md。這個管理後台的說明可以直接在電腦及手機閱讀。
