Programar una campaña

POST /api/v1/campaigns/{campaignId}/schedule Reserva el envío de una campaña draft para un instante futuro y responde 202. Llamado sobre una campaña que ya está scheduled, la mueve al nuevo instante. Esta llamada no envía nada: la campaña sale sola a la hora reservada.

Autorización

Rol en la organizaciónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 403
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

Cuerpo de la solicitud

CampoTipoObligatorioDescripción
scheduledAtstringsíInstante ISO 8601 con un desfase explícito, al menos un minuto en el futuro
json
{"scheduledAt": "2026-08-12T07:00:00Z"}

Ejemplo

bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt": "2026-08-12T07:00:00Z"}' \
  "https://www.agentsmail.io/api/v1/campaigns/$CAMPAIGN_ID/schedule"

Respuesta

  • 202 Accepted: la campaña queda scheduled para el instante devuelto en scheduledAt.
  • 400 Bad Request: scheduledAt falta, no tiene desfase, está en el pasado o a menos de un minuto (details indica el problema); o el contenido no tiene enlace de baja.
  • 401 Unauthorized: clave ausente o no válida, o su propietario dejó la organización.
  • 403 Forbidden: el propietario de la clave es member de la organización, no admin.
  • 404 Not Found: no existe esa campaña, o pertenece a otra organización. La API nunca confirma que un id existe a quien no tiene derecho sobre él.
  • 409 Conflict: el dominio de envío aún no está verificado, el saldo no cubre a los destinatarios de la campaña, su lista se retiró, o la campaña está paused, sending, sent o failed. No se reserva nada.
  • 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
data.campaignIdstringLa campaña programada
data.statusstringSiempre scheduled
data.scheduledAtstringEl instante realmente guardado, en UTC, redondeado al minuto

Ejemplo de respuesta

json
{
  "success": true,
  "data": {
    "campaignId": "6c6c6c6c-5555-4aaa-8bbb-999900001111",
    "status": "scheduled",
    "scheduledAt": "2026-08-12T07:00:00.000Z"
  }
}

Notas

Una fecha sin zona horaria se rechaza; nunca se interpreta como UTC. 2026-08-12T09:00:00 responde 400: la API no adivina un desfase que no escribiste. Escribe 2026-08-12T07:00:00Z o 2026-08-12T09:00:00+02:00: ambos designan el mismo instante.
  • La programación se guarda al minuto: los segundos que envíes se descartan. Lee scheduledAt en la respuesta para conocer la salida exacta.
  • Volver a llamarlo sobre una campaña scheduled mueve la salida; el horario anterior deja de valer. Una campaña nunca tiene más de una salida.
  • Una campaña paused responde 409: reanúdala en la app, o devuélvela a borrador con Desprogramar una campaña y vuelve a programarla.
  • Para enviar ya, usa Enviar una campaña.
Nunca programes sin la aprobación humana explícita para esa campaña concreta. Una campaña programada sale sola; la aprobación de un envío nunca cubre el siguiente.

Relacionado