Labels

List contact labels

contacts.labels.list

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.

Scope

contacts:read

Permission

View the module

MCP tool

contacts_labels_listOn the full surface; on the compact one, mb_execute_operation with id: "contacts.labels.list".

Declared cost: up to 500 reads and 0 writes per call (they count against the daily quota).

Parameters

No parameters.

Response

Errors

Example

curl "https://api.mb-suite.com/v1/contacts/labels" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl "https://api.mb-suite.com/v1/contacts/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create a contact label

contacts.labels.create

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.

Scope

contacts:write

Permission

Edit in the module

MCP tool

contacts_labels_createOn the full surface; on the compact one, mb_execute_operation with id: "contacts.labels.create".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X POST "https://api.mb-suite.com/v1/contacts/labels" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X POST "https://api.mb-suite.com/v1/contacts/labels" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME"
}'

Update a contact label

contacts.labels.update

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.

Scope

contacts:write

Permission

Edit in the module

MCP tool

contacts_labels_updateOn the full surface; on the compact one, mb_execute_operation with id: "contacts.labels.update".

Declared cost: up to 1 reads and 1 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X PATCH "https://api.mb-suite.com/v1/contacts/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X PATCH "https://api.mb-suite.com/v1/contacts/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Delete a contact label

contacts.labels.delete

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.

With an API key, this DELETE runs directly: the record stays 30 days in the trash and the response carries its trash_item_id. With an OAuth token, and through the MCP, it needs dry_run → confirm_token.

Scope

contacts:write and “Allow deletions” (contacts:delete in OAuth)

Permission

Edit in the module

MCP tool

contacts_labels_deleteOn the full surface; on the compact one, mb_execute_operation with id: "contacts.labels.delete".

Declared cost: up to 5001 reads and 5001 writes per call (they count against the daily quota).

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/contacts/labels/{label_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Try it with your test API key

With a test API key the request always goes to your practice organization: example data you can reset.

curl -X DELETE "https://api.mb-suite.com/v1/contacts/labels/{label_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"