# 구독자 API 레퍼런스

Source: https://instatus.com/help/ko/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/ko/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"
  }
}
```