Añadir o actualizar un contacto

POST /api/v1/lists/{listId}/contacts Añade un contacto a una lista, o completa el que ya está: la dirección de email es la clave, dentro de esa lista. Este es el endpoint al que llama un embudo o un lead magnet: a diferencia de la importación en bloque, produce efectos secundarios, así que se dispara un evento de inscripción y sale una confirmación de doble opt-in cuando la organización la exige.

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.

Parámetros de ruta

Parámetro	Tipo	Descripción
`listId`	string	Obligatorio. La lista a la que se une el contacto. Un contacto pertenece exactamente a una

Cuerpo de la solicitud

Campo	Tipo	Obligatorio	Descripción
`email`	string	sí	La clave de la inserción o actualización, junto con la lista. Debe ser una dirección válida
`firstName`	string	no	Hasta 100 caracteres
`tags`	string[]	no	Nombres de etiquetas, de 1 a 50 caracteres cada uno. Se crean en la organización si todavía no existen
`doubleOptIn`	boolean	no	Campo heredado, aceptado pero ignorado. Solo el ajuste de suscripción de la organización decide si se exige confirmación

json

{
  "email": "ada@example.com",
  "firstName": "Ada",
  "tags": ["vip", "webinar-march"]
}

Ejemplo

bash

curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@example.com", "firstName": "Ada", "tags": ["vip"]}' \
  "https://www.agentsmail.io/api/v1/lists/$LIST_ID/contacts"

Respuesta

200 OK: el contacto, creado o completado. No 201: la semántica es la de un upsert, y la llamada no te permite saber cuál de los dos casos ocurrió.
400 Bad Request: dirección no válida, una etiqueta de más de 50 caracteres, un cuerpo mal formado; 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.
404 Not Found: no existe esa lista, o pertenece a otra organización. La API nunca confirma que un id existe a un llamante que no tiene derecho sobre él.
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 contacto
`data.email`	string	Su dirección: única dentro de su lista
`data.firstName`	string \| null	Lo que sabes de la persona
`data.lastName`	string \| null	Este endpoint nunca lo establece; viene de una importación o de la interfaz
`data.status`	string	`pending`, `subscribed`, `unsubscribed`, `bounced`, `complained`
`data.listId`	string	La lista a la que pertenece
`data.list`	object	`{id, name}` de esa lista
`data.tags`	array	`{id, name}` de cada etiqueta que lleva después de la llamada
`data.createdAt`	string	Fecha de creación ISO
`data.updatedAt`	string	Fecha ISO del último cambio

Ejemplo de respuesta