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 organization | This endpoint |
|---|---|
OWNER | Allowed |
ADMIN | Allowed |
MEMBER | Refused — 403 |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
key | string | yes | Lowercase letters, digits and _, starting with a letter, 40 characters at most. Unique in the organization |
label | string | yes | 1 to 100 characters |
type | string | yes | text, 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:detailscarries the field-level issues. Also, withoutdetails, 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 amemberof the organization, not anadmin.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
| Field | Type | Description |
|---|---|---|
success | boolean | Indicates if the operation was successful |
data.id | string | Unique identifier for the field |
data.key | string | The key values are written under |
data.label | string | The name people read |
data.type | string | text, number, date or boolean |
data.createdAt | string | ISO creation date |
data.updatedAt | string | ISO 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 a409, 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.