Menú

Referencia de la API · Email Marketing

Audiencias

email_marketing · audiences · 7 operaciones

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

LecturaIdempotenteDesde 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.

Alcance: email_marketing:read
Permiso: Ver el módulo
Tool del MCP: email_marketing_audiences_listEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.list".

Costo declarado: hasta 202 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

limitintegerqueryopcional

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

Por defecto: 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

Respuesta

dataarray<object>

has_moreboolean

next_cursorstring

Errores

invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

LecturaIdempotenteDesde 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.

Alcance: email_marketing:read
Permiso: Ver el módulo
Tool del MCP: email_marketing_audiences_getEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.get".

Costo declarado: hasta 1 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

audience_idstringrutarequerido

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

Respuesta

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

Errores

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

LecturaIdempotenteDesde 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.

Alcance: email_marketing:read
Permiso: Ver el módulo
Tool del MCP: email_marketing_audiences_members_listEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.members.list".

Costo declarado: hasta 260 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).

Parámetros

audience_idstringrutarequerido

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).

Por defecto: 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.

Respuesta

dataarray<object>

has_moreboolean

totalnumber

next_cursorstring

Errores

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient module_access_denied operation_not_found rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

EscrituraDesde 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.

Alcance: email_marketing:write
Permiso: Editar en el módulo
Tool del MCP: email_marketing_audiences_createEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.create".

Costo declarado: hasta 10000 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

namestringcuerporequerido

The audience's name.

typeenumcuerporequerido

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

descriptionstringcuerpoopcional

Internal description.

contact_idsarray<string>cuerpoopcional

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

filter_label_idsarray<string>cuerpoopcional

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

filter_label_modeenumcuerpoopcional

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

Valores: any, all

filter_org_idsarray<string>cuerpoopcional

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

imported_membersarray<object>cuerpoopcional

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

Respuesta

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.

Errores

invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

EscrituraIdempotenteDesde 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.

Alcance: email_marketing:write
Permiso: Editar en el módulo
Tool del MCP: email_marketing_audiences_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.update".
Eventos que puede emitir: email_marketing.audience.updated

Costo declarado: hasta 1 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

audience_idstringrutarequerido

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

updatesobjectcuerporequerido

The fields to change.

Respuesta

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.

Errores

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

EscrituraIdempotenteDesde 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.

Alcance: email_marketing:write
Permiso: Ver el módulo
Tool del MCP: email_marketing_audiences_refresh_countEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.refresh_count".

Costo declarado: hasta 10001 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).

Parámetros

audience_idstringrutarequerido

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

Respuesta

countnumber

Errores

email_audience_not_found invalid_input unknown_field authentication_required scope_insufficient crm_action_denied idempotency_key_reused rate_limited quota_exceeded

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes 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

IrreversibleDesde 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.

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: email_marketing:write y «Permitir eliminar» (email_marketing:delete en OAuth)
Permiso: Editar en el módulo
Tool del MCP: email_marketing_audiences_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "email_marketing.audiences.delete".

Costo declarado: hasta 1 lecturas y 2 escrituras por llamada (cuentan en el cupo diario).

Parámetros

audience_idstringrutarequerido

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

Errores

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

Ejemplo

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

Probar con tu API key de prueba

Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.

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