API-Referenz für Abonnenten

Abonnenten abrufen

Endpunkt:

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

• Die Standard-Seitennummer ist 1.
• Der Standardwert für per_page ist 50, das Maximum sind 100 Einträge pro Seite.
• Mit der optionalen Suchabfrage filtern Sie Abonnenten nach E-Mail-Adresse oder Telefonnummer.
• Mit dem optionalen status filtern Sie Abonnenten nach ihrem Abonnementstatus. Verwenden Sie status=confirmed, um alle auszulassen, die noch nicht bestätigt haben.

Wert	Zurückgegebene Abonnenten
confirmed	Bestätigte Abonnenten, die Benachrichtigungen erhalten.
unconfirmed	Freigegebene Abonnenten, die ihr Abonnement noch nicht bestätigt haben.
unapproved	Abonnenten, die auf Freigabe warten, z. B. importierte Listen.

Beispielantwort

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

Einen Abonnenten hinzufügen

Endpunkt:

POST /v1/:page_id/subscribers

Beim Abonnieren richtet sich das Bestätigungsverhalten nach der Einstellung subscriberConfirmationMode der Seite. Mit autoConfirm an diesem Endpunkt überschreiben Sie dieses Verhalten für einen einzelnen Abonnenten.

Beispielanfrage

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

• autoConfirm — optional. Bei true wird der Abonnent sofort hinzugefügt, ohne Bestätigungs- oder Willkommens-E-Mail, unabhängig von der Seiteneinstellung. Nur Pro.

Beispielantwort

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

Bestimmte Komponenten abonnieren

Beispielanfrage

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

Beispielantwort

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

Mehrere Abonnenten hinzufügen

Endpunkt:

POST /v1/:page_id/subscribers/bulk

Über diesen Endpunkt erstellen Sie mehrere Abonnenten in einer einzigen Anfrage.

Beispielanfrage

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

• autoConfirm gilt für jeden Abonnenten im Batch. Nur Pro.

Beispielantwort

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

Antwort, wenn einzelne Abonnenten fehlschlagen

Wenn einzelne Abonnenten nicht erstellt werden können (z. B. doppelte E-Mail-Adresse, falsches Format), enthält die Antwort Details zu den Fehlern:

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

Hinweise:

• Maximal 100 Abonnenten pro Anfrage
• Jedes Abonnentenobjekt kann dieselben Felder enthalten wie beim Endpunkt für einzelne Abonnenten
• Teilweiser Erfolg wird unterstützt – erfolgreich erstellte Abonnenten werden auch dann zurückgegeben, wenn einzelne fehlschlagen

Bestätigungsverhalten

Statusseiten steuern über subscriberConfirmationMode am Endpunkt Eine Statusseite aktualisieren, wie neue Abonnenten behandelt werden:

Wert	Verhalten
REQUIRED	Abonnenten müssen per E-Mail bestätigen, bevor sie Updates erhalten. Standard.
WELCOME	Abonnenten werden sofort hinzugefügt und erhalten eine Willkommens-E-Mail. Nur Pro.
NONE	Abonnenten werden sofort ohne E-Mail hinzugefügt. Nur Pro.

Der Parameter autoConfirm an den Erstellungs-Endpunkten überschreibt die Seiteneinstellung für diese Anfrage und verhält sich wie NONE.

Einen Abonnenten entfernen

Endpunkt:

DELETE /v1/:page_id/subscribers/:subscriber_id

Beispielantwort

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