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.
Escopo
contacts:read
Permissão
Ver o módulo
Tool do MCP
contacts_labels_listNa superfície completa; na compacta, mb_execute_operation com id: "contacts.labels.list".
Custo declarado: até 500 leituras e 0 escritas por chamada (contam na cota diária).
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.
Escopo
contacts:write
Permissão
Editar no módulo
Tool do MCP
contacts_labels_createNa superfície completa; na compacta, mb_execute_operation com id: "contacts.labels.create".
Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).
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.
Escopo
contacts:write
Permissão
Editar no módulo
Tool do MCP
contacts_labels_updateNa superfície completa; na compacta, mb_execute_operation com id: "contacts.labels.update".
Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).
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.
Com uma API key, este DELETE roda direto: o registro fica 30 dias na lixeira e a resposta traz o seu trash_item_id. Com um token OAuth, e pelo MCP, pede dry_run → confirm_token.
Escopo
contacts:writee «Permitir exclusões» (contacts:delete no OAuth)
Permissão
Editar no módulo
Tool do MCP
contacts_labels_deleteNa superfície completa; na compacta, mb_execute_operation com id: "contacts.labels.delete".
Custo declarado: até 5001 leituras e 5001 escritas por chamada (contam na cota diária).
Parâmetros
label_idstringrotaobrigatório
The label's id (from contacts.labels.list).
Resposta
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.
