Referencia de la API de suscriptores

Obtener los suscriptores

Endpoint:

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

• El número de página por defecto es 1.
• El valor por defecto de per_page es 50 y el máximo es de 100 elementos por página.
• La consulta de búsqueda opcional filtra los suscriptores por dirección de correo o número de teléfono.

Respuesta de ejemplo

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

Añadir un suscriptor

Endpoint:

POST /v1/:page_id/subscribers

Cuando alguien se suscribe, el comportamiento de confirmación sigue el ajuste subscriberConfirmationMode de la página. Usa autoConfirm en este endpoint para cambiar ese comportamiento en un suscriptor concreto.

Petición de ejemplo

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

• autoConfirm: opcional. Con el valor true, añade al suscriptor al momento sin enviar correos de confirmación ni de bienvenida, sea cual sea el ajuste de la página. Solo Pro.

Respuesta de ejemplo

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

Suscribirse a componentes concretos

Petición de ejemplo

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

Respuesta de ejemplo

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

Añadir varios suscriptores

Endpoint:

POST /v1/:page_id/subscribers/bulk

Este endpoint te permite crear varios suscriptores en una sola petición.

Petición de ejemplo

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

• autoConfirm se aplica a todos los suscriptores del lote. Solo Pro.

Respuesta de ejemplo

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

Respuesta cuando fallan algunos suscriptores

Si algunos suscriptores no se pueden crear (por ejemplo, correo duplicado o formato incorrecto), la respuesta incluirá los detalles de los fallos:

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

Notas:

• Máximo 100 suscriptores por petición
• Cada objeto de suscriptor puede tener los mismos campos que el endpoint de suscriptor individual
• Se admite el éxito parcial: se devuelven los suscriptores creados correctamente aunque algunos fallen

Comportamiento de la confirmación

Las páginas de estado controlan cómo se gestionan los suscriptores nuevos mediante subscriberConfirmationMode en el endpoint Actualizar una página de estado:

Valor	Comportamiento
REQUIRED	Los suscriptores deben confirmar por correo antes de recibir actualizaciones. Es el valor por defecto.
WELCOME	Los suscriptores se añaden al momento y reciben un correo de bienvenida. Solo Pro.
NONE	Los suscriptores se añaden al momento y no reciben ningún correo. Solo Pro.

El parámetro autoConfirm de los endpoints de creación tiene prioridad sobre el ajuste de la página en esa petición y se comporta como NONE.

Eliminar un suscriptor

Endpoint:

DELETE /v1/:page_id/subscribers/:subscriber_id

Respuesta de ejemplo

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