【Breaking Change】Newsleopard Contacts API 行為調整公告（2026/5/1 起生效）

親愛的 Newsleopard 用戶您好：

為了優化 Newsleopard 資料，提升數據品質，我們將於 2026/5/1 起，調整系統的「群組名單匯入及變數管理機制」。

並於 2026/2/1 先行推出輔助功能，協助您提前檢視與調整現有變數欄位設定，確保未來使用不受影響。

本次調整將影響部分名單相關 API 的資料處理行為，敬請您務必提前留意。

更版時程說明

• 2026/2/1
  • 新增「變數欄位留存」輔助功能，協助您提前檢視與調整現有變數欄位設定
  • API 用戶需透過後台進行變數設定（目前尚未提供變數管理 API）
• 2026/5/1
  • 正式啟用新的名單匯入機制與變數規範（詳見下方說明）

2026/5/1 起的三項重要調整

1. 名單匯入 API 行為調整（Breaking Change）

自 2026/5/1 起，透過下列 API 匯入名單時：

• 名單變數 需事先於 Newsleopard 後台建立
• 若 API 傳入的變數欄位尚未建立：
  • 該欄位資料 將被自動忽略
  • 不會再於匯入時自動新增變數欄位

受影響的 API：

• /v1/contacts/imports/{list_sn}/file
• /v1/contacts/imports/{list_sn}/text

2. 變數數量限制

• 每個帳號 最多可使用 20 個變數欄位
• 超過 20 個的變數：
  • 會被設定為「停用」狀態
  • 「停用」狀態的變數欄位，無法匯入資料
  • 「停用」狀態的變數欄位，無法用於信件插入變數

👉 已存在的資料不會被刪除，但停用中的變數將無法再使用。

3. 超過 20 個變數的替代方案（不受限制）

若您的寄送情境中，單次信件需使用 超過 20 個變數，可改採「單次上傳名單並建立活動寄信」的 API 進行操作：

• 此方式 不受 20 個變數上限限制
• 適合一次性或高變數需求的寄送情境

「單次上傳名單並建立活動寄信」API 文件

4. 變數命名規則調整（系統保留字）

為避免與系統欄位衝突，以下為 系統保留字，未來將無法作為變數名稱（不分大小寫）：

此外，系統將限制變數名稱可用的特殊符號：

可使用：

• 英文字母（a–z / A–Z）
• 數字
• 中文
• 日文
• 半形 -
• 半形 _

不可使用：

• 空白
• 特殊符號（例：@ # $ % ^ & * 等）
• 全形英數（例：ＡＢＣ、１２３）

👉 若您目前有使用上述名稱作為自訂變數，請提前調整。

Newsleopard 團隊 敬上