Crear una campaña

POST /api/v1/campaigns Crea una campaña en draft. Responde 201.

El contenido se copia de la plantilla, no forma parte del cuerpo. Edita la plantilla y luego crea la campaña: una campaña nunca se aparta de lo que renderizaste. tagId recibe un id, no un nombre: resuélvelo con GET /api/v1/tags.topicId funciona igual, y se resuelve con GET /api/v1/topics. Un contenido que lleva {{topicOptOutUrl}} en una campaña sin tema hace que el envío sea rechazado: el enlace estaría muerto. Consulta Temas.

sendingIdentityId recibe un id de tu libreta de direcciones: lístalas con GET /api/v1/settings/identities, donde cada entrada lleva su id, su senderEmail y si es la predeterminada. Una dirección que pertenece a otra organización se rechaza con 403.Omitirlo no equivale a fijar la predeterminada. Una campaña sin sendingIdentityId sigue la predeterminada tal como esté en el momento del envío: si promueves otra dirección, esa campaña la sigue. Una campaña que nombra una dirección la conserva, sea cual sea la predeterminada después. Consulta Ajustes y dominios para la libreta de direcciones en sí.

Autorización

Rol en la organización	Este endpoint
`OWNER`	Permitido
`ADMIN`	Permitido
`MEMBER`	Rechazado — `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.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	sí	De 1 a 100 caracteres, nombre interno
`subject`	string	sí	De 1 a 200 caracteres, el asunto que ven los destinatarios
`previewText`	string \| null	no	Texto de vista previa, hasta 200 caracteres tras recortar espacios. `null` lo borra; omitido en PATCH lo conserva. Se renderiza en `{{previewText}}` o `{{preheader}}`
`preheader`	string \| null	no	Alias compatible de `previewText`. Si se envían ambos, deben coincidir tras recortar espacios; si no, `400`
`templateId`	string	sí	Plantilla de tu organización
`listId`	string	sí	Lista a la que enviar
`tagId`	string	no	Acota la lista a los contactos que llevan esta etiqueta
`topicId`	string	no	Tema editorial que lleva esta campaña. Obligatorio para que `{{topicOptOutUrl}}` se renderice
`sendingIdentityId`	string	no	La dirección que firma esta campaña. Omitido o `null`: la predeterminada de la organización

json

{
  "name": "August newsletter",
  "subject": "What shipped in August",
  "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.",
  "templateId": "2b2b2b2b-3333-4ddd-8eee-ffff00001111",
  "listId": "9f8e7d6c-1111-4bbb-8ccc-ddddeeeeffff"
}

Usa un solo alias. Si ambos están presentes, deben coincidir tras recortar espacios, null incluido; valores en conflicto devuelven 400. Una cadena vacía también elimina el texto de vista previa.

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{
    "name": "August newsletter",
    "subject": "What shipped in August",
    "previewText": "Timely m’a bloqué mes paiements Stripe pendant 5 jours.",
    "templateId": "'$TEMPLATE_ID'",
    "listId": "'$LIST_ID'",
    "sendingIdentityId": "'$IDENTITY_ID'"
  }' \
  "https://www.agentsmail.io/api/v1/campaigns"

Respuesta

400 Bad Request: campos no válidos, texto de vista previa de más de 200 caracteres o alias en conflicto.
201 Created: el recurso creado.
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.
429 Too Many Requests: más de 120 solicitudes en un minuto para esta clave.

Campos de la respuesta

Campo	Tipo	Descripción
`success`	boolean	Indica si la operación tuvo éxito
`data`	object	Objeto de campaña.
`data.campaignUrl`	string \| null	Página de la campaña.
`data.campaignEditorUrl`	string \| null	Editor del contenido de un borrador editable.
`data.campaignStatsUrl`	string \| null	Estadísticas de una campaña enviada.
`data.campaignPreviewUrl`	string \| null	Vista previa interna de una campaña enviada.
`data.publicCampaignUrl`	string \| null	Archivo compartible de una campaña enviada con archivos públicos activados.
`data.id`	string	Identificador único de la campaña
`data.name`	string	Su nombre interno
`data.subject`	string	El asunto que ven los destinatarios
`data.previewText`	string \| null	Texto de vista previa guardado; igual a `data.preheader`
`data.preheader`	string \| null	El texto de vista previa que se muestra tras el asunto, `null` si no hay
`data.status`	string	`draft`, `scheduled`, `paused`, `sending`, `sent`, `failed`
`data.listId`	string	La lista a la que apunta
`data.tagId`	string	null
`data.topicId`	string	null
`data.scheduledAt`	string	null
`data.sentAt`	string	null
`data.createdAt`	string	Fecha ISO de creación
`data.updatedAt`	string	Fecha ISO del último cambio

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