Audiences

List audiences

email_marketing.audiences.list

Lists the organization's email audiences, most recently updated first, paginated by cursor: name, type (static: chosen contacts; dynamic_labels: contacts with some or all of the given labels; dynamic_orgs: contacts assigned to the given accounts; csv: imported addresses), filters and the last member count. Filter by type (applies to the page read: follow next_cursor until has_more is false). Contact ids and imported members are not included: use email_marketing.audiences.get or email_marketing.audiences.members.list. Requires view access to Email Marketing.

Scope

email_marketing:read

Permission

View the module

MCP tool

email_marketing_audiences_listOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/email-marketing/audiences" \
  -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/email-marketing/audiences" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get one audience

email_marketing.audiences.get

Returns an audience with its definition: the contact ids of a static audience, the label filter (and mode any/all) of a dynamic_labels one, the accounts of a dynamic_orgs one, or the imported members of a csv one, plus the last member count. For the resolved list of people use email_marketing.audiences.members.list. Not found (email_audience_not_found) if it is not an audience of this organization. Requires view access to Email Marketing.

Scope

email_marketing:read

Permission

View the module

MCP tool

email_marketing_audiences_getOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.get".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_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 "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

List the people in an audience today

email_marketing.audiences.members.list

Lists the members an audience has today, the way a flow enrollment resolves it (contacts with an email of this organization: the chosen ones, the ones with the labels, the ones assigned to the accounts, or the imported list), one page at a time (email, name, contact_id, source) with a real cursor: each page reads only its own contacts. Contacts without an email and, in an «all labels» audience, contacts missing one of the labels are left out of the page, so a page can bring fewer than limit while has_more is true: follow next_cursor until has_more is false. total is the audience size: exact for imported lists, the number of chosen contacts for static audiences, and the contacts that match the filter for dynamic ones (an upper bound when some lack an email). Suppressed addresses are listed (sending skips them). Requires view access to Email Marketing.

Scope

email_marketing:read

Permission

View the module

MCP tool

email_marketing_audiences_members_listOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.members.list".

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

Parameters

Response

Errors

Example

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/members" \
  -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/email-marketing/audiences/{audience_id}/members" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Create an audience

email_marketing.audiences.create

Creates an audience: static (contact_ids of Contacts, plus optional loose addresses in imported_members), dynamic_labels (filter_label_ids of Contacts, filter_label_mode any or all), dynamic_orgs (filter_org_ids: the accounts whose assigned contacts enter) or csv (imported_members: up to 10,000 { email, name }). Imported rows without a valid email, or repeated (same email ignoring case), are left out and returned in rejected_members (rejected_count says how many). Dynamic audiences are resolved once to store the member count. Returns audience_id and member_count. Requires full access to Email Marketing.

Scope

email_marketing:write

Permission

Edit in the module

MCP tool

email_marketing_audiences_createOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.create".

Declared cost: up to 10000 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/email-marketing/audiences" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "type": "static"
}'

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/email-marketing/audiences" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "NAME",
  "type": "static"
}'

Update an audience

email_marketing.audiences.update

Updates an audience's name, description or definition (contact_ids, filter_label_ids and filter_label_mode, filter_org_ids, imported_members; the type does not change). Lists replace the previous ones. Flows linked to the audience pick up the change at their next sync; campaigns resolve it when they are sent. For a dynamic audience refresh the count with email_marketing.audiences.refresh_count. Imported rows without a valid email, or repeated, are left out and returned in rejected_members. Returns the updated audience. Requires full access to Email Marketing.

Scope

email_marketing:write

Permission

Edit in the module

MCP tool

email_marketing_audiences_updateOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.update".

Events it can emit

email_marketing.audience.updated

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/email-marketing/audiences/{audience_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/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "updates": {}
}'

Recount an audience's members

email_marketing.audiences.refresh_count

Resolves the audience again and stores today's member count (dynamic audiences change as contacts get labels or accounts). It changes nothing else. Returns count. Requires view access to Email Marketing (it only refreshes a derived number), and a credential with write scope.

Scope

email_marketing:write

Permission

View the module

MCP tool

email_marketing_audiences_refresh_countOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.refresh_count".

Declared cost: up to 10001 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/email-marketing/audiences/{audience_id}/refresh-count" \
  -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 POST "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/refresh-count" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Delete an audience

email_marketing.audiences.delete

Deletes an audience; it goes to the 30-day trash. Flows linked to it drop the link at their next sync (restoring the audience does not relink them) and a campaign that still points to it cannot be sent until another audience is chosen. Contacts are not touched. Outside the screen it requires a dry run and a confirm_token, or a REST DELETE. Requires full access to Email Marketing.

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

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

Permission

Edit in the module

MCP tool

email_marketing_audiences_deleteOn the full surface; on the compact one, mb_execute_operation with id: "email_marketing.audiences.delete".

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

Parameters

Response

Errors

Example

curl -X DELETE "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_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/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"