Lists the organization's contact labels (name, hex color, order) in the order the Contacts screen shows them. Use their ids in the label_ids of contacts, in the label_id filter of contacts.contacts.list and in the label filters of Email Marketing audiences and flows. These are not the CRM labels.
Alcance
contacts:read
Permiso
Ver el módulo
Tool del MCP
contacts_labels_listEn la superficie completa; en la compacta, mb_execute_operation con id: "contacts.labels.list".
Costo declarado: hasta 500 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Creates a contact label at the end of the list: name (up to 60 characters) and an optional hex color such as #3b82f6 (without it, a color of the screen's palette). Returns label_id and the label. It does not check for another label with the same name, like the screen.
Alcance
contacts:write
Permiso
Editar en el módulo
Tool del MCP
contacts_labels_createEn la superficie completa; en la compacta, mb_execute_operation con id: "contacts.labels.create".
Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).
Renames a contact label, changes its hex color or its position in the list (order, 0 = first), sent inside updates. The contacts that carry it keep it. Returns the updated label.
Alcance
contacts:write
Permiso
Editar en el módulo
Tool del MCP
contacts_labels_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "contacts.labels.update".
Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).
Deletes a contact label and removes it from every contact that carried it (the contacts are not otherwise changed and no webhook event is sent for them). The label definition goes to the 30-day trash; restoring it brings the label back and puts it back on all those contacts (the ones deleted meanwhile are skipped). Up to 5,000 contacts: with more, the deletion stops before writing anything with 409 too_many_labeled_contacts (delete it from the app). Email Marketing audiences and flows that filter by this label stop matching it. Outside the app it requires a dry run (which says how many contacts carry it) and a confirm_token, except a REST DELETE with a key allowed to delete.
Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.
Alcance
contacts:writey «Permitir eliminar» (contacts:delete en OAuth)
Permiso
Editar en el módulo
Tool del MCP
contacts_labels_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "contacts.labels.delete".
Costo declarado: hasta 5001 lecturas y 5001 escrituras por llamada (cuentan en el cupo diario).
Parámetros
label_idstringrutarequerido
The label's id (from contacts.labels.list).
Respuesta
oktrue
trash_item_idstring
The trash item this deletion left: the item_id of platform.trash.restore (POST /trash/{item_id}/restore). Missing if nothing went to the trash.
trash_item_idsarray<string>
Only when the deletion left more than one copy: all of them, the first being trash_item_id.
trash_expires_atnumber
When the copy leaves the trash for good (epoch ms): 30 days after the deletion.
