Справочник API по подписчикам

Получить подписчиков

Эндпоинт:

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

• Номер страницы по умолчанию — 1.
• Значение per_page по умолчанию — 50, максимум — 100 элементов на страницу.
• Необязательный поисковый запрос фильтрует подписчиков по адресу email или номеру телефона.
• Необязательный параметр status фильтрует подписчиков по статусу подписки. Используйте status=confirmed, чтобы исключить тех, кто ещё не подтвердил подписку.

Значение	Возвращаемые подписчики
confirmed	Подтверждённые подписчики, которые получают уведомления.
unconfirmed	Одобренные подписчики, которые ещё не подтвердили подписку.
unapproved	Подписчики, ожидающие одобрения, например из импортированных списков.

Пример ответа

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

Добавить подписчика

Эндпоинт:

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

Ответ, когда часть подписчиков не создана

Если часть подписчиков создать не удалось (например, дубликат email или неверный формат), ответ будет содержать подробности об ошибках:

{
  "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	Подписчики должны подтвердить подписку по email, прежде чем получать обновления. По умолчанию.
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"
  }
}