Crear un tema

POST /api/v1/topics Crea un tema. Responde 201 con el tema creado: su id es el topicId que asignas a una campaña o a una secuencia. Un nombre ya usado —sin distinguir mayúsculas, así que Freelancing choca con freelancing— responde 409.

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 sobre AgentsMail en sí. Consulta Claves de API.

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`name`	string	sí	De 1 a 50 caracteres

json

{"name": "freelancing"}

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"name":"freelancing"}' \
  "https://www.agentsmail.io/api/v1/topics"

Respuesta

201 Created: el tema creado.
400 Bad Request: el nombre falta, está vacío o supera los 50 caracteres; details lleva los problemas por campo.
401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.
403 Forbidden: el propietario de la clave es member de la organización, no admin.
409 Conflict: otro tema ya lleva ese nombre, sin distinguir mayúsculas. No se creó nada; lista los temas y reutiliza el id existente.
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 se realizó correctamente
`data.id`	string	Identificador único del tema
`data.name`	string	Nombre del tema, único en la organización
`data.createdAt`	string	Fecha de creación ISO
`data.updatedAt`	string	Fecha ISO del último cambio

Ejemplo de respuesta

json

{
  "success": true,
  "data": {
    "id": "7c2e4b19",
    "name": "freelancing",
    "createdAt": "2026-08-23T10:22:05.000Z",
    "updatedAt": "2026-08-23T10:22:05.000Z"
  }
}

Receta para agentes

Reutiliza antes de crear: una segunda llamada con un nombre ya usado solo te cuesta un 409:

const existing = await list('/api/v1/topics')
const topic =
  existing.data.find((t) => t.name.toLowerCase() === 'freelancing') ??
  (await post('/api/v1/topics', {name: 'freelancing'})).data

await post('/api/v1/campaigns', {
  name: 'Freelance news',
  subject: 'This month for freelancers',
  templateId,
  listId,
  topicId: topic.id,
})

Notas

Crear un tema no cambia nada por sí solo. Empieza a importar el día en que una campaña o una secuencia lo lleva.