Crear un campo personalizado

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ónEste endpoint
OWNERPermitido
ADMINPermitido
MEMBERRechazado — 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

CampoTipoObligatorioDescripción
keystringsíLetras minúsculas, dígitos y _, empezando por una letra, 40 caracteres como máximo. Única en la organización
labelstringsíDe 1 a 100 caracteres
typestringsí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: details lleva los problemas por campo. También, sin details, 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 es member de la organización, no admin.
  • 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

CampoTipoDescripción
successbooleanIndica si la operación tuvo éxito
data.idstringIdentificador único del campo
data.keystringLa clave bajo la que se escriben los valores
data.labelstringEl nombre que se lee
data.typestringtext, number, date o boolean
data.createdAtstringFecha de creación ISO
data.updatedAtstringFecha 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 un 409, 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.

Relacionado