POST /api/v1/custom-fields
Crea un campo personalizado. Responde 201 con el campo creado; desde entonces, los contactos aceptan un valor bajo su key.
La key y el type se fijan al crear el campo: elígelos con cuidado, después solo se puede renombrar la etiqueta.
Autorización
| Rol en la organización | Este endpoint |
|---|---|
OWNER | Permitido |
ADMIN | Permitido |
MEMBER | Rechazado — 403 |
Cuerpo de la solicitud
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
key | string | sí | Letras minúsculas, dígitos y _, empezando por una letra, 40 caracteres como máximo. Única en la organización |
label | string | sí | De 1 a 100 caracteres |
type | string | sí | text, number, date o boolean (sí/no) |
json
{"key": "utm_source", "label": "UTM source", "type": "text"}Ejemplo
bash
curl -X POST -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
-d '{"key":"utm_source","label":"UTM source","type":"text"}' \
"https://www.agentsmail.io/api/v1/custom-fields"Respuesta
201 Created: el campo creado.400 Bad Request: falta un campo, la etiqueta es demasiado larga o el tipo es desconocido:detailslleva los problemas por campo. También, sindetails, cuando la clave está mal formada (UTM-Source), cuando está reservada (email,status…), o cuando la organización ya tiene 50 campos; el mensaje dice cuál.401 Unauthorized: clave ausente o no válida, o su propietario salió de la organización.403 Forbidden: el propietario de la clave esmemberde la organización, noadmin.409 Conflict: otro campo ya usa esa clave. No se creó nada; lista los campos y reutiliza el 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 tuvo éxito |
data.id | string | Identificador único del campo |
data.key | string | La clave bajo la que se escriben los valores |
data.label | string | El nombre que se lee |
data.type | string | text, number, date o boolean |
data.createdAt | string | Fecha de creación ISO |
data.updatedAt | string | Fecha ISO del último cambio |
Ejemplo de respuesta
json
{
"success": true,
"data": {
"id": "4f1a9c2e",
"key": "utm_source",
"label": "UTM source",
"type": "text",
"createdAt": "2026-11-15T10:22:05.000Z",
"updatedAt": "2026-11-15T10:22:05.000Z"
}
}Receta para agentes
Reutiliza antes de crear: una clave ya tomada solo te cuesta un409, y un campo cuyo tipo no coincide con tus datos ya no se puede cambiar:
js
const existing = await list('/api/v1/custom-fields')
const field =
existing.data.find((f) => f.key === 'utm_source') ??
(await post('/api/v1/custom-fields', {
key: 'utm_source',
label: 'UTM source',
type: 'text',
})).data
await post(`/api/v1/lists/${listId}/contacts`, {
email: 'ada@example.com',
customFields: {[field.key]: 'newsletter'},
})Notas
- Crear un campo no escribe nada en ningún contacto: todos empiezan sin valor.