Référence de l’API Abonnés

Récupérer les abonnés

Point de terminaison :

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

• Le numéro de page par défaut est 1.
• La valeur par défaut de per_page est 50, avec un maximum de 100 éléments par page.
• Le paramètre de recherche facultatif permet de filtrer les abonnés par adresse e-mail ou numéro de téléphone.

Exemple de réponse

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

Ajouter un abonné

Point de terminaison :

POST /v1/:page_id/subscribers

Lorsqu’une personne s’abonne, le comportement de confirmation suit le réglage subscriberConfirmationMode de la page. Utilisez autoConfirm sur ce point de terminaison pour le remplacer pour un abonné donné.

Exemple de requête

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

• autoConfirm — facultatif. Lorsqu’il vaut true, l’abonné est ajouté immédiatement sans envoi d’e-mail de confirmation ou de bienvenue, quel que soit le paramètre de la page. Pro uniquement.

Exemple de réponse

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

S’abonner à des composants précis

Exemple de requête

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

Exemple de réponse

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

Ajouter plusieurs abonnés

Point de terminaison :

POST /v1/:page_id/subscribers/bulk

Ce point de terminaison permet de créer plusieurs abonnés en une seule requête.

Exemple de requête

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

• autoConfirm s’applique à tous les abonnés du lot. Pro uniquement.

Exemple de réponse

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

Réponse lorsque certains abonnés échouent

Si la création de certains abonnés échoue (e-mail en double, format incorrect, etc.), la réponse contient le détail des échecs :

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

Remarques :

• 100 abonnés maximum par requête
• Chaque objet abonné peut contenir les mêmes champs que le point de terminaison d’abonné unique
• Le succès partiel est pris en charge : les abonnés créés avec succès sont renvoyés même si certains échouent

Comportement de confirmation

Les pages de statut contrôlent le traitement des nouveaux abonnés via subscriberConfirmationMode sur le point de terminaison Mettre à jour une page de statut :

Valeur	Comportement
REQUIRED	Les abonnés doivent confirmer par e-mail avant de recevoir les mises à jour. Valeur par défaut.
WELCOME	Les abonnés sont ajoutés immédiatement et reçoivent un e-mail de bienvenue. Pro uniquement.
NONE	Les abonnés sont ajoutés immédiatement, sans e-mail. Pro uniquement.

Le paramètre autoConfirm des points de terminaison de création remplace le réglage de la page pour cette requête et se comporte comme NONE.

Retirer un abonné

Point de terminaison :

DELETE /v1/:page_id/subscribers/:subscriber_id

Exemple de réponse

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