Obtener una campaña

GET /api/v1/campaigns/{campaignId} Devuelve una campaña con su número de destinatarios en tiempo real y el progreso del envío. recipientCount se calcula a partir del objetivo actual; no es una estimación guardada.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERPermitido
Una clave lleva el rol que su creador tiene en esta organización, nunca un rol en AgentsMail en sí. Consulta Claves de API.

Parámetros de ruta

ParámetroTipoDescripción
campaignIdstringIdentificador único de una campaña

Ejemplo

bash
curl -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID"

Respuesta

  • 200 OK: la campaña y su información de envío actual.
  • 401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
  • 404 Not Found: no existe esa campaña, o pertenece a otra organización.
  • 429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

CampoTipoDescripción
successbooleanIndica si la operación tuvo éxito
dataobjectObjeto de campaña.
data.campaignUrlstring | nullPágina de la campaña.
data.campaignEditorUrlstring | nullEditor del contenido de un borrador editable.
data.campaignStatsUrlstring | nullEstadísticas de una campaña enviada.
data.campaignPreviewUrlstring | nullVista previa interna de una campaña enviada.
data.publicCampaignUrlstring | nullArchivo compartible de una campaña enviada con archivos públicos activados.
data.idstringIdentificador único de la campaña
data.namestringNombre interno de la campaña
data.subjectstringAsunto que ven los destinatarios
data.previewTextstring | nullTexto de vista previa guardado; igual a data.preheader
data.preheaderstring | nullTexto de vista previa que se muestra tras el asunto; null si no hay
data.contentstringContenido HTML enviado a los destinatarios
data.statusstringdraft, scheduled, paused, sending, sent, failed o deleted
data.templateIdstring | nullPlantilla de origen, cuando la campaña se creó a partir de una
data.listIdstringLista a la que apunta la campaña
data.tagIdstring | nullEtiqueta opcional que acota la lista
data.topicIdstring | nullTema editorial que lleva esta campaña, si lo hay
data.sendingIdentityIdstring | nullIdentidad de remitente seleccionada; null usa la identidad predeterminada
data.scheduledAtstring | nullHora de salida programada en formato ISO 8601; se conserva mientras está paused
data.sentAtstring | nullHora de finalización en formato ISO 8601
data.createdAtstringHora de creación en formato ISO 8601
data.updatedAtstringÚltimo cambio de la campaña en formato ISO 8601
data.recipientCountnumberContactos suscritos que coinciden con el objetivo en este momento
data.progress.totalnumberRegistros de envío creados para la campaña
data.progress.sentnumberMensajes confirmados como enviados
data.progress.failednumberMensajes que terminaron en fallo
data.progress.pendingnumberMensajes aún no intentados
data.progress.sendingnumberMensajes reservados actualmente para su procesamiento
data.progress.staleSendingnumberMensajes reservados cuya ventana de procesamiento ha expirado
data.progress.lastActivityAtstring | nullActividad de envío real más reciente: sentAt para un mensaje despachado, hora de la transición terminal para un mensaje fallido u omitido
data.progress.chunkSizenumberNúmero de mensajes asignados a un lote de procesamiento
data.sendingEnabledbooleanSi el envío de campañas está activado actualmente en todo AgentsMail
Los cinco enlaces son URL absolutas en el idioma de la organización (en por defecto). Los enlaces no disponibles son null; todos son null si la organización no tiene slug de URL. Los enlaces internos requieren iniciar sesión y tener acceso a la organización; solo publicCampaignUrl es público. Los agentes API y MCP muestran las URL pertinentes no nulas como enlaces Markdown, por ejemplo [Abrir campaña](campaignUrl) con la URL recibida. Crear o consultar una campaña no la publica.

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "id": "4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "name": "Newsletter",
    "subject": "August news",
    "previewText": "Three new things this month",
    "preheader": "Three new things this month",
    "content": "<p>Hello {{firstName}}</p>",
    "status": "sending",
    "templateId": null,
    "listId": "0b7c51e8-5df6-4e87-9fc2-d272dca63214",
    "tagId": "7c2ef4b1-94da-46df-b2c4-b390282adf64",
    "topicId": null,
    "sendingIdentityId": null,
    "scheduledAt": "2026-08-23T10:22:05.000Z",
    "sentAt": null,
    "createdAt": "2026-08-23T10:20:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z",
    "recipientCount": 1240,
    "progress": {
      "total": 1240,
      "sent": 1200,
      "failed": 2,
      "pending": 35,
      "sending": 3,
      "staleSending": 1,
      "lastActivityAt": "2026-08-23T10:31:44.000Z",
      "chunkSize": 14
    },
    "sendingEnabled": true,
    "campaignUrl": "https://www.agentsmail.io/es/team/my-team/campaigns/4d19c0a2-75ba-4c3e-a0b2-f8a759282c4d",
    "campaignEditorUrl": null,
    "campaignStatsUrl": null,
    "campaignPreviewUrl": null,
    "publicCampaignUrl": null
  }
}

Notas

  • staleSending está incluido en sending; no sumes los dos valores.
  • Las aperturas y los clics no actualizan lastActivityAt.
  • Un valor de staleSending distinto de cero no prueba que un mensaje no fuera aceptado. No lo reenvíes automáticamente.
  • recipientCount excluye los contactos dados de baja, con rebote o con queja.

Relacionado