Rename a custom field

PATCH /api/v1/custom-fields/{customFieldId} Changes the label of a custom field. Nothing else moves: values are stored under the key, which stays the same. The label is the only thing this call changes. A body carrying key or type is refused with 400 rather than half-applied — to change either, create a new field.

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.

Path parameters

ParameterTypeDescription
customFieldIdstringRequired. The field to rename

Request body

FieldTypeRequiredDescription
labelstringyes1 to 100 characters. No other field is accepted
json
{"label": "Acquisition source"}

Example

bash
curl -X PATCH -H "x-api-key: $AGENTMAIL_API_KEY" -H "content-type: application/json" \
  -d '{"label":"Acquisition source"}' \
  "https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"

Response

  • 200 OK — the renamed field.
  • 400 Bad Request — the label is missing, empty or over 100 characters, or the body carries another field such as key or type; details carries the issues.
  • 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.
  • 404 Not Found — no such field, or it belongs to another organization. The API never confirms that an id exists to a caller who has no right to it.
  • 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, unchanged
data.labelstringIts new label
data.typestringThe type, unchanged
data.createdAtstringISO creation date
data.updatedAtstringISO date of the last change

Example response

json
{
  "success": true,
  "data": {
    "id": "4f1a9c2e",
    "key": "utm_source",
    "label": "Acquisition source",
    "type": "text",
    "createdAt": "2026-11-02T08:11:00.000Z",
    "updatedAt": "2026-11-15T10:22:05.000Z"
  }
}

Notes

  • Two fields may share a label, never a key: a rename is never refused for a label already in use.