Riferimento API degli iscritti

Ottenere gli iscritti

Endpoint:

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

• Il numero di pagina predefinito è 1.
• Il valore predefinito di per_page è 50 e il massimo è 100 elementi per pagina.
• Il parametro di ricerca facoltativo filtra gli iscritti per indirizzo email o numero di telefono.

Esempio di risposta

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

Aggiungere un iscritto

Endpoint:

POST /v1/:page_id/subscribers

Quando qualcuno si iscrive, il comportamento di conferma segue l'impostazione subscriberConfirmationMode della pagina. Usa autoConfirm su questo endpoint per forzare un comportamento diverso per un singolo iscritto.

Esempio di richiesta

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

• autoConfirm — facoltativo. Se true, aggiunge subito l'iscritto senza inviare email di conferma o di benvenuto, a prescindere dall'impostazione della pagina. Solo Pro.

Esempio di risposta

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

Iscriversi a componenti specifici

Esempio di richiesta

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

Esempio di risposta

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

Aggiungere più iscritti

Endpoint:

POST /v1/:page_id/subscribers/bulk

Questo endpoint ti permette di creare più iscritti con una sola richiesta.

Esempio di richiesta

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

• autoConfirm vale per tutti gli iscritti del gruppo. Solo Pro.

Esempio di risposta

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

Risposta quando alcuni iscritti non vengono creati

Se alcuni iscritti non vengono creati (ad esempio per email duplicata o formato errato), la risposta includerà i dettagli degli errori:

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

Note:

• Massimo 100 iscritti per richiesta
• Ogni oggetto iscritto può avere gli stessi campi dell'endpoint per il singolo iscritto
• Il successo parziale è supportato: gli iscritti creati correttamente vengono restituiti anche se altri falliscono

Comportamento di conferma

Le status page stabiliscono come gestire i nuovi iscritti tramite subscriberConfirmationMode sull'endpoint Aggiornare una status page:

Valore	Comportamento
REQUIRED	Gli iscritti devono confermare via email prima di ricevere gli aggiornamenti. Valore predefinito.
WELCOME	Gli iscritti vengono aggiunti subito e ricevono un'email di benvenuto. Solo Pro.
NONE	Gli iscritti vengono aggiunti subito senza alcuna email. Solo Pro.

Il parametro autoConfirm sugli endpoint di creazione ha la precedenza sull'impostazione della pagina per quella richiesta e si comporta come NONE.

Rimuovere un iscritto

Endpoint:

DELETE /v1/:page_id/subscribers/:subscriber_id

Esempio di risposta

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