Delete a custom field

DELETE /api/v1/custom-fields/{customFieldId} Deletes a custom field.
Deleting a field erases its value on every contact, in every list, at once. There is no undo.

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 delete

Example

bash
curl -X DELETE -H "x-api-key: $AGENTMAIL_API_KEY" \
  "https://www.agentsmail.io/api/v1/custom-fields/$CUSTOM_FIELD_ID"

Response

  • 200 OK — the id of what was removed.
  • 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.idstringIdentifier of what was removed

Example response

json
{
  "success": true,
  "data": {
    "id": "4f1a9c2e"
  }
}

Agent recipe

Find the field by its key, then delete it by its id:
js
const fields = (await list('/api/v1/custom-fields')).data
const field = fields.find((f) => f.key === 'utm_source')

if (field) {
  await del(`/api/v1/custom-fields/${field.id}`)
}

Notes

  • It is final. The values are gone for every contact, and creating a field with the same key afterwards starts empty.
  • Once the field is gone, sending its key in a contact's customFields is refused again.