Referência da API · Email Marketing

Audiências

email_marketing · audiences · 7 operações

GET/v1/email-marketing/audiencesList audiences GET/v1/email-marketing/audiences/{audience_id}Get one audience GET/v1/email-marketing/audiences/{audience_id}/membersList the people in an audience today POST/v1/email-marketing/audiencesCreate an audience PATCH/v1/email-marketing/audiences/{audience_id}Update an audience POST/v1/email-marketing/audiences/{audience_id}/refresh-countRecount an audience's members DELETE/v1/email-marketing/audiences/{audience_id}Delete an audience

GET/v1/email-marketing/audiences

List audiences

email_marketing.audiences.list

LeituraIdempotenteDesde 2026-11-01

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.

Escopo: email_marketing:read
Permissão: Ver o módulo
Tool do MCP: email_marketing_audiences_listNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.list".

Custo declarado: até 202 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

limitintegerqueryopcional

How many items this page brings at most (see the maximum and the default in the schema).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

typeenumqueryopcional

Only audiences of this type: static, dynamic_labels, dynamic_orgs or csv.

Valores: static, dynamic_labels, dynamic_orgs, csv

Resposta

dataarray<object>

has_moreboolean

next_cursorstring

Erros

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/email-marketing/audiences" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/email-marketing/audiences" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/email-marketing/audiences/{audience_id}

Get one audience

email_marketing.audiences.get

LeituraIdempotenteDesde 2026-11-01

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.

Escopo: email_marketing:read
Permissão: Ver o módulo
Tool do MCP: email_marketing_audiences_getNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.get".

Custo declarado: até 1 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

audience_idstringrotaobrigatório

The audience's id (from email_marketing.audiences.list).

Resposta

idstring

namestring

typestring

descriptionstring | null

member_countnumber | null

contact_idsarray<string> | null

filter_label_idsarray<string> | null

filter_label_modestring | null

filter_org_idsarray<string> | null

imported_membersarray<object> | null

created_bystring | null

created_atnumber | null

updated_atnumber | null

Erros

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

GET/v1/email-marketing/audiences/{audience_id}/members

List the people in an audience today

email_marketing.audiences.members.list

LeituraIdempotenteDesde 2026-11-01

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.

Escopo: email_marketing:read
Permissão: Ver o módulo
Tool do MCP: email_marketing_audiences_members_listNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.members.list".

Custo declarado: até 260 leituras e 0 escritas por chamada (contam na cota diária).

Parâmetros

audience_idstringrotaobrigatório

The audience's id (from email_marketing.audiences.list).

limitintegerqueryopcional

How many items this page brings at most (see the maximum and the default in the schema).

Padrão: 50

cursorstringqueryopcional

The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.

Resposta

dataarray<object>

has_moreboolean

totalnumber

next_cursorstring

Erros

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Exemplo

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/members" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/members" \
  -H "Authorization: Bearer $MB_TEST_KEY"

POST/v1/email-marketing/audiences

Create an audience

email_marketing.audiences.create

EscritaDesde 2026-11-01

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.

Escopo: email_marketing:write
Permissão: Editar no módulo
Tool do MCP: email_marketing_audiences_createNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.create".

Custo declarado: até 10000 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

namestringcorpoobrigatório

The audience's name.

typeenumcorpoobrigatório

static (chosen contacts), dynamic_labels (contacts with some labels), dynamic_orgs (contacts of some Accounts) or csv (imported members).

Valores: static, dynamic_labels, dynamic_orgs, csv

descriptionstringcorpoopcional

Internal description.

contact_idsarray<string>corpoopcional

With type static: contacts of Contacts (ids of contacts.contacts.list).

filter_label_idsarray<string>corpoopcional

With type dynamic_labels: contact labels (ids of contacts.labels.list, up to 30).

filter_label_modeenumcorpoopcional

With dynamic_labels: any (one of the labels) or all of them.

Valores: any, all

filter_org_idsarray<string>corpoopcional

With type dynamic_orgs: Accounts whose assigned contacts enter (ids of platform.orgs.list).

imported_membersarray<object>corpoopcional

With type csv (or the loose emails of a static one): the imported members (up to 10,000).

Resposta

audience_idstring

member_countnumber

rejected_countnumber

How many imported rows were left out (invalid email or repeated).

rejected_membersarray<object>

The first 100 rows left out, with why: invalid_email or duplicate.

Erros

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

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"
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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"
}'

PATCH/v1/email-marketing/audiences/{audience_id}

Update an audience

email_marketing.audiences.update

EscritaIdempotenteDesde 2026-11-01

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.

Escopo: email_marketing:write
Permissão: Editar no módulo
Tool do MCP: email_marketing_audiences_updateNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.update".
Eventos que pode emitir: email_marketing.audience.updated

Custo declarado: até 1 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

audience_idstringrotaobrigatório

The audience's id (from email_marketing.audiences.list).

updatesobjectcorpoobrigatório

The fields to change.

Resposta

audienceobject

rejected_countnumber

How many imported rows were left out (invalid email or repeated).

rejected_membersarray<object>

The first 100 rows left out, with why: invalid_email or duplicate.

Erros

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

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": {}
}'

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

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": {}
}'

POST/v1/email-marketing/audiences/{audience_id}/refresh-count

Recount an audience's members

email_marketing.audiences.refresh_count

EscritaIdempotenteDesde 2026-11-01

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.

Escopo: email_marketing:write
Permissão: Ver o módulo
Tool do MCP: email_marketing_audiences_refresh_countNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.refresh_count".

Custo declarado: até 10001 leituras e 1 escritas por chamada (contam na cota diária).

Parâmetros

audience_idstringrotaobrigatório

The audience's id (from email_marketing.audiences.list).

Resposta

countnumber

Erros

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X POST "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/refresh-count" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X POST "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}/refresh-count" \
  -H "Authorization: Bearer $MB_TEST_KEY"

DELETE/v1/email-marketing/audiences/{audience_id}

Delete an audience

email_marketing.audiences.delete

IrreversívelDesde 2026-11-01

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.

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: email_marketing:write e «Permitir exclusões» (email_marketing:delete no OAuth)
Permissão: Editar no módulo
Tool do MCP: email_marketing_audiences_deleteNa superfície completa; na compacta, mb_execute_operation com id: "email_marketing.audiences.delete".

Custo declarado: até 1 leituras e 2 escritas por chamada (contam na cota diária).

Parâmetros

audience_idstringrotaobrigatório

The audience's id (from email_marketing.audiences.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.

Erros

email_audience_not_found delete_not_allowed confirmation_required invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Exemplo

curl -X DELETE "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_API_KEY"

Testar com a sua API key de teste

Com uma API key de teste o pedido vai sempre para a sua organização de prática: dados de exemplo que você pode reiniciar.

curl -X DELETE "https://api.mb-suite.com/v1/email-marketing/audiences/{audience_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"