# 订阅者 API 参考

Source: https://instatus.com/help/zh/api/subscribers

## 获取订阅者

**端点：**

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

- page 默认为 1。
- per_page 默认为 50，每页最多 100 条。
- 可选的 search 查询参数用于按电子邮箱地址或手机号筛选订阅者。
- 可选的 `status` 按订阅状态筛选订阅者。使用 `status=confirmed` 可排除尚未确认的订阅者。

| 取值 | 返回的订阅者 |
| --- | --- |
| `confirmed` | 已确认并接收通知的订阅者。 |
| `unconfirmed` | 已审批但尚未确认订阅的订阅者。 |
| `unapproved` | 等待审批的订阅者，例如导入的列表。 |

**响应示例**

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

## 添加订阅者

**端点：**

```bash
POST /v1/:page_id/subscribers
```

有人订阅时，确认行为遵循页面的 `subscriberConfirmationMode` 设置。你可以在这个端点上使用 `autoConfirm`，为单个订阅者覆盖该行为。

**请求示例**

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

- `autoConfirm` —— 可选。设为 `true` 时，无论页面设置如何，都会立即添加订阅者，不发送确认邮件或欢迎邮件。仅 Pro 可用。

**响应示例**

```json
{
  "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"
  }
}
```

### 订阅特定组件

**请求示例**

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

**响应示例**

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

## 批量添加订阅者

**端点：**

```bash
POST /v1/:page_id/subscribers/bulk
```

这个端点允许你在一次请求中创建多个订阅者。

**请求示例**

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

- `autoConfirm` 对这一批中的每个订阅者都生效。仅 Pro 可用。

**响应示例**

```json
{
  "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": []
  }
}
```

**部分订阅者创建失败时的响应**

如果部分订阅者创建失败（例如邮箱重复、格式不正确），响应中会包含失败的详细信息：

```json
{
  "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 位订阅者
- 每个订阅者对象可以使用与单个订阅者端点相同的字段
- 支持部分成功——即使有部分失败，也会返回成功创建的订阅者

## 确认行为

状态页通过[更新状态页](https://instatus.com/help/zh/api/status-pages)端点上的 `subscriberConfirmationMode` 来控制如何处理新订阅者：

| 取值 | 行为 |
| --- | --- |
| `REQUIRED` | 订阅者必须先通过邮件确认才能收到更新。默认值。 |
| `WELCOME` | 订阅者会被立即添加，并收到一封欢迎邮件。仅 Pro 可用。 |
| `NONE` | 订阅者会被立即添加，不发送任何邮件。仅 Pro 可用。 |

创建类端点上的 `autoConfirm` 参数会为该次请求覆盖页面设置，行为等同于 `NONE`。

## 移除订阅者

**端点：**

```bash
DELETE /v1/:page_id/subscribers/:subscriber_id
```

**响应示例**

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