訂閱者 API 參考

取得訂閱者

端點：

GET /v2/:page_id/subscribers?page=:page&per_page=:per_page&search=:search_query

page 預設為 1。
per_page 預設為 50，每頁最多 100 筆。
選填的 search 查詢參數可用電子郵件地址或電話號碼篩選訂閱者。

回應範例

[
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": "ali@instatus.com",
    "phone": null,
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "all": true,
    "components": []
  },
  {
    "id": "cm1111x6ofgsd5666mzxcw978qh",
    "email": null,
    "phone": "5417543010",
    "webhook": null,
    "webhookEmail": null,
    "confirmed": false,
    "all": true,
    "components": []
  }
]

新增訂閱者

端點：

POST /v1/:page_id/subscribers

有人訂閱時，確認流程會依照頁面的 subscriberConfirmationMode 設定。你可以在這個端點使用 autoConfirm，針對單一訂閱者覆寫該行為。

請求範例

{
  "email": "sarah@instatus.com",
  "all": true,
  "autoConfirm": false
}

autoConfirm — 選填。設為 true 時，會立即新增訂閱者，不寄送確認信或歡迎信，且不受頁面設定影響。僅限 Pro。

回應範例

{
  "id": "cm1111x6ofgsd5666mzxcw978df",
  "name": null,
  "email": "sarahs@instatus.com",
  "phone": null,
  "confirmed": false,
  "all": true,
  "createdAt": "2024-10-01T03:48:41.474Z",
  "updatedAt": "2024-10-01T03:48:41.474Z",
  "siteId": "cm1111x6ofgsd5666mzxcw978qh",
  "unsubscribeToken": "e3b51de6-1234-4664-zxyv-1679gg524260",
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "discordTeam": null,
  "slack": null,
  "slackTeam": null,
  "language": "en",
  "company": null,
  "microsoftTeamsWebhook": null,
  "googleChatWebhook": null,
  "googleChatSpace": null,
  "failedAttempts": 0,
  "approved": true,
  "importedFrom": null,
  "hideUnsubLink": false,
  "webhookIncidentBody": null,
  "webhookMaintenanceBody": null,
  "webhookComponentBody": null,
  "webhookHttpMethod": "POST",
  "webhookHeaders": null,
  "site": {
    "id": "cm1111x6ofgsd5666mzxcw978qh"
  }
}

只訂閱特定元件

請求範例

{
  "email": "adam@instatus.com",
  "all": false,
  "components": ["cl2xv23rl0119e7jlk2mweepd"],
  "autoConfirm": false
}

回應範例

{
  "id": "cl09gt11151422bjluflghewx",
  "email": "adam@instatus.com",
  "site": {
    "id": "ckg8a112344s5v86wrn",
    "name": "Test",
    "logoUrl": null,
    "subdomain": "test",
    "publicEmail": null,
    "language": "en"
  }
}

新增多位訂閱者

端點：

POST /v1/:page_id/subscribers/bulk

這個端點讓你在單一請求中建立多位訂閱者。

請求範例

{
  "subscribers": [
    {
      "email": "sarah@instatus.com",
      "all": true
    },
    {
      "email": "john@instatus.com",
      "components": ["cl2xv23rl0119e7jlk2mweepd"]
    },
    {
      "name": "Jane Doe",
      "phone": "5417543010",
      "all": true
    }
  ],
  "autoConfirm": false
}

autoConfirm 會套用到這批中的每一位訂閱者。僅限 Pro。

回應範例

{
  "success": true,
  "created": 3,
  "failed": 0,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "phone": null,
        "confirmed": false,
        "all": false,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm3333x6ofgsd5666mzxcw978df",
        "email": null,
        "phone": "5417543010",
        "name": "Jane Doe",
        "confirmed": false,
        "all": true,
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": []
  }
}

部分訂閱者建立失敗時的回應

如果部分訂閱者建立失敗（例如電子郵件重複、格式錯誤），回應中會包含失敗的詳細資訊：

{
  "success": false,
  "created": 2,
  "failed": 1,
  "results": {
    "created": [
      {
        "id": "cm1111x6ofgsd5666mzxcw978df",
        "email": "sarah@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      },
      {
        "id": "cm2222x6ofgsd5666mzxcw978df",
        "email": "john@instatus.com",
        "site": {
          "id": "cm1111x6ofgsd5666mzxcw978qh"
        }
      }
    ],
    "failed": [
      {
        "index": 2,
        "subscriber": {
          "email": "duplicate@instatus.com",
          "all": true
        },
        "error": {
          "code": "creation_failed",
          "message": "Subscriber with this email already exists"
        }
      }
    ]
  }
}

注意事項：

每個請求最多 100 位訂閱者
每個訂閱者物件可使用與單一訂閱者端點相同的欄位
支援部分成功 — 即使有部分失敗，仍會回傳成功建立的訂閱者

確認流程

狀態頁透過更新狀態頁端點上的 subscriberConfirmationMode 來控制新訂閱者的處理方式：

值	行為
`REQUIRED`	訂閱者必須先透過電子郵件確認才會收到更新。這是預設值。
`WELCOME`	訂閱者會立即新增並收到一封歡迎信。僅限 Pro。
`NONE`	訂閱者會立即新增，且不寄送任何郵件。僅限 Pro。

建立端點上的 autoConfirm 參數會針對該次請求覆寫頁面設定，行為與 NONE 相同。

移除訂閱者

端點：

DELETE /v1/:page_id/subscribers/:subscriber_id

回應範例

{
  "id": "cm1zvzm3434dlp9255d6jgy8",
  "name": null,
  "email": "sarah@instatus.com",
  "phone": null,
  "webhook": null,
  "webhookEmail": null,
  "discord": null,
  "microsoftTeamsWebhook": null,
  "company": null,
  "site": {
    "id": "cm180slpo000g9343478qh"
  }
}