Create a custom field

POST /api/v1/custom-fields Creates a custom field. Answers 201 with the created field — from then on, contacts accept a value under its key. The key and the type are fixed at creation: choose them carefully, only the label can be renamed later.

Authorization

Role in the organizationThis endpoint
OWNERAllowed
ADMINAllowed
MEMBERRefused — 403
A key carries the role its creator holds in this organization — never a role on AgentsMail itself. See API keys.

Request body

FieldTypeRequiredDescription
keystringyesLowercase letters, digits and _, starting with a letter, 40 characters at most. Unique in the organization
labelstringyes1 to 100 characters
typestringyestext, number, date or boolean (yes/no)
json
{"key": "utm_source", "label": "UTM source", "type": "text"}

Example

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"

Response

  • 201 Created — the created field.
  • 400 Bad Request — a field is missing, the label is too long or the type is unknown: details carries the field-level issues. Also, without details, when the key is badly formed (UTM-Source), when it is reserved (email, status…), or when the organization already has 50 fields — the message says which.
  • 401 Unauthorized — missing or invalid key, or its owner left the organization.
  • 403 Forbidden — the key's owner is a member of the organization, not an admin.
  • 409 Conflict — another field already uses that key. Nothing was created; list the fields and reuse the existing one.
  • 429 Too Many Requests — over 120 requests in a minute for this key.

Response fields

FieldTypeDescription
successbooleanIndicates if the operation was successful
data.idstringUnique identifier for the field
data.keystringThe key values are written under
data.labelstringThe name people read
data.typestringtext, number, date or boolean
data.createdAtstringISO creation date
data.updatedAtstringISO date of the last change

Example response

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"
  }
}

Agent recipe

Reuse before creating — a key already taken just costs you a 409, and a field whose type does not match your data cannot be changed afterwards:
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'},
})

Notes

  • Creating a field writes nothing on any contact: every contact starts with no value for it.