API-referentie voor abonnees

Abonnees ophalen

Endpoint:

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

• Het standaard paginanummer is 1.
• De standaardwaarde voor per_page is 50; het maximum is 100 items per pagina.
• Met de optionele zoekopdracht filter je abonnees op e-mailadres of telefoonnummer.
• Met de optionele status filter je abonnees op hun abonnementsstatus. Gebruik status=confirmed om iedereen weg te laten die nog niet heeft bevestigd.

Waarde	Teruggegeven abonnees
confirmed	Bevestigde abonnees die meldingen ontvangen.
unconfirmed	Goedgekeurde abonnees die hun abonnement nog niet hebben bevestigd.
unapproved	Abonnees die wachten op goedkeuring, zoals geïmporteerde lijsten.

Voorbeeldrespons

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

Een abonnee toevoegen

Endpoint:

POST /v1/:page_id/subscribers

Wanneer iemand zich abonneert, volgt het bevestigingsgedrag de instelling subscriberConfirmationMode van de pagina. Gebruik autoConfirm op dit endpoint om dat gedrag voor één abonnee te overschrijven.

Voorbeeldverzoek

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

• autoConfirm — optioneel. Bij true wordt de abonnee meteen toegevoegd, zonder bevestigings- of welkomstmail, ongeacht de instelling van de pagina. Alleen Pro.

Voorbeeldrespons

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

Abonneren op bepaalde componenten

Voorbeeldverzoek

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

Voorbeeldrespons

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

Meerdere abonnees toevoegen

Endpoint:

POST /v1/:page_id/subscribers/bulk

Met dit endpoint maak je meerdere abonnees aan in één verzoek.

Voorbeeldverzoek

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

• autoConfirm geldt voor elke abonnee in de batch. Alleen Pro.

Voorbeeldrespons

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

Respons wanneer sommige abonnees mislukken

Lukt het aanmaken van sommige abonnees niet (bijvoorbeeld door een dubbel e-mailadres of een onjuist formaat), dan bevat de respons details over de fouten:

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

Opmerkingen:

• Maximaal 100 abonnees per verzoek
• Elk abonnee-object mag dezelfde velden bevatten als bij het endpoint voor één abonnee
• Gedeeltelijk succes wordt ondersteund: succesvol aangemaakte abonnees worden teruggegeven, ook als er een paar mislukken

Bevestigingsgedrag

Statuspagina's bepalen via subscriberConfirmationMode op het endpoint Een statuspagina bijwerken hoe nieuwe abonnees worden afgehandeld:

Waarde	Gedrag
REQUIRED	Abonnees moeten per e-mail bevestigen voordat ze updates krijgen. Standaard.
WELCOME	Abonnees worden meteen toegevoegd en krijgen een welkomstmail. Alleen Pro.
NONE	Abonnees worden meteen toegevoegd, zonder e-mail. Alleen Pro.

De parameter autoConfirm op de aanmaak-endpoints overschrijft de instelling van de pagina voor dat verzoek en gedraagt zich als NONE.

Een abonnee verwijderen

Endpoint:

DELETE /v1/:page_id/subscribers/:subscriber_id

Voorbeeldrespons

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