E-mail

Send an email from a connected mailbox

crm.email.send

Sends an email through the mailbox the sender connected in their personal integrations (Gmail, Outlook or IMAP/SMTP) and records it as an outbound email activity linked to the given deal or person (or to the person whose email matches a recipient), so it shows in every linked timeline; a deal_id or person_id that does not exist is not_found before anything is sent. Variables {{firstName}}, {{lastName}}, {{fullName}}, {{email}}, {{company}}, {{jobTitle}}, {{dealTitle}}, {{dealValue}}, {{dealCurrency}} and {{dealStage}} in subject and body are filled in before sending. To reply inside a thread pass thread_id and reply_to_message_id, from crm.email.threads.get: that operation reads the mailbox content, so an API key or a third-party app has it only when the organization's owner allows connected mailbox content and the credential was granted it (MIA never reads it); without it, send a new email. sender_user_id sends from another member's mailbox (owners, admins and CRM admins only); the mailboxes to send from, their ids and aliases are in crm.email.senders.list. from_alias must be an alias enabled for that mailbox (not available for Outlook). Attachments must already be stored under the organization's email attachments (uploading files is not available through the API). The dry run checks what the send checks before going out (the sender's mailbox, the alias, the deal or person, the attachments' place) without calling the mail provider, and warns about variables that go out as written or empty and about an email that no timeline will show. Not idempotent: retrying sends the email again; when the mail provider does not confirm the send it answers external_outcome_unknown (the email may have gone out: check the sent folder before sending it again). A person marked «Do not contact» or unsubscribed gets nothing that starts the contact: when a recipient (to or cc, by any of the person's emails) is one of them, nothing is sent and the answer is 409 do_not_contact, with the addresses and why in details.recipients and whether it can be confirmed in details.overridable. Only a person of the team can confirm it, on a closed basis (do_not_contact_override: about their account, a charge or support, or because the person asked us to write), with a reason outside the app (3 to 500 characters; without it, 400 do_not_contact_reason_required); it is recorded in the audit log and on the activity. An AI agent's API key cannot confirm it (403 do_not_contact_override_not_allowed, and its 409 says overridable false). A reply in a thread (thread_id) where that person wrote last, after being marked (within the last 24 hours for a mark from before 2026-10-16), goes out without confirmation. When the email goes out to one of them, the response carries do_not_contact: the recipients, allowed_as (reply or override) and, when confirmed, the basis. The dry run gives the same answer or says why it goes out anyway. Requires edit access to the CRM and the send_email permission (owners, admins and members; never viewers). In the practice organization (test keys) nothing is sent: the outbound activity is recorded as simulated and the response carries simulated: true.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Escopo

crm:write

Permissão

Editar no módulo · Ação do CRM: send_email

Tool do MCP

crm_email_sendNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.send".

Custo declarado: até 470 leituras e 12 escritas por chamada (contam na cota diária). Usa uma plataforma externa (gmail): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "TO"
  ],
  "subject": "SUBJECT",
  "body_html": "BODY_HTML",
  "dry_run": true
}'

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. Na prática esta operação é simulada: nada é enviado e a resposta traz simulated: true.

curl -X POST "https://api.mb-suite.com/v1/crm/emails" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": [
    "TO"
  ],
  "subject": "SUBJECT",
  "body_html": "BODY_HTML",
  "dry_run": true
}'

List the mailboxes the caller can send from, and which need reconnecting

crm.email.senders.list

Lists the mailboxes to send from: the connected ones the caller can send an email from, their own, or every active mailbox of the organization for owners, admins and CRM admins. The mailboxes the CRM reads and syncs (the email inbox, by privacy) are in crm.email.mailboxes.list: the same connections, seen for reading. Each sender's id is the sender_user_id to pass to crm.email.send, with the send-as aliases enabled for that mailbox (can_send is false for Outlook aliases), status connected and ses_fallback (the address is also a verified SES sender of the organization, so a sequence keeps sending through it if the mailbox connection drops; otherwise its contacts pause with gmail_connection_lost). default_sender_id is the caller's own mailbox when it is connected, otherwise the first of the list (null when there is none). needs_reconnect lists, with the same reach, the mailboxes whose connection dropped (the provider rejected the stored token): nothing is sent from them, sequences included, until their owner reconnects them in Integrations in the app (there is no API for that); provider says which one (google_gmail, microsoft_outlook, imap_smtp) and since says when it was marked, if known. caller_mailbox is the caller's own mailbox: connected, reconnect_required or not_connected. Read from what MB Suite stores: it does not call Google or Microsoft. Requires view access to the CRM.

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_email_senders_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.senders.list".

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

Parâmetros

Sem parâmetros.

Resposta

Erros

Exemplo

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

List the email signatures of a CRM user

crm.email.signatures.list

Returns the email signatures (name, HTML, which one is the default) of a CRM user: the caller's own by default, or another member's (user_id) for owners, admins and CRM admins. Append the default one at the end of the body of crm.email.send when the user expects their signature. Signatures are created and edited from the screen only.

Escopo

crm:read

Permissão

Ver o módulo

Tool do MCP

crm_email_signatures_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.signatures.list".

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

Parâmetros

Resposta

Erros

Exemplo

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

List the mailboxes the CRM reads and syncs

crm.email.mailboxes.list

Lists the mailboxes to read and sync: the connected mailboxes (Gmail, Outlook or IMAP) of the CRM team whose emails become CRM activities and make the email inbox, the ones the caller is allowed to read, with the owner's user_id and name, the mailbox address, its status (a dropped one stops syncing), last sync and privacy mode. Private mailboxes of other users are left out (owners, admins and CRM admins see all); an API key, a third-party app and MIA see only the mailbox of the user they act as. To send an email, the mailboxes to send from are in crm.email.senders.list: the same connections, seen for sending (only the active ones, with their aliases). The user_id is the owner_user_id of crm.email.mailbox.sync and of the crm.email.threads operations; those read the mailbox content, so an API key or a third-party app has them only when the organization's owner allows connected mailbox content and the credential was granted it (MIA never has them).

Escopo

crm:read

Permissão

Ver o módulo · Ação do CRM: view_inbox

Tool do MCP

crm_email_mailboxes_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.mailboxes.list".

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

Parâmetros

Sem parâmetros.

Resposta

Erros

Exemplo

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

List the email threads of a mailbox

crm.email.threads.list

For API keys and third-party apps this operation exists only when the organization's owner allows connected mailbox content and the credential was granted it; even then it returns only threads linked to a CRM person, company or deal (person_id, company_id or deal_id present), never the whole mailbox. Lists the threads of one mailbox (owner_user_id, from crm.email.mailboxes.list) in a folder: inbox (default), sent or archived; a thread you replied to lives in both inbox and sent. Newest first, paginated by cursor (limit up to 200), built from the mailbox's latest 500 emails (up to 200 threads). Each thread has its subject, last snippet, participants, message and unread counts and the person, deal or company it is linked to. A private mailbox, or one that does not exist, returns an empty list. Use crm.email.threads.get for the messages.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:read

Permissão

Ver o módulo · Ação do CRM: view_inbox

Tool do MCP

crm_email_threads_listNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.list".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads" \
  -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/crm/emails/mailboxes/{owner_user_id}/threads" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Get the messages of an email thread

crm.email.threads.get

For API keys and third-party apps this operation exists only when the organization's owner allows connected mailbox content and the credential was granted it; a thread with no link to a CRM person, company or deal is not found for them. Returns the messages of a thread of a mailbox, oldest first: direction, from, to, cc, subject, the sanitized HTML body, a text preview, the date, the linked CRM ids (linked_person_ids, linked_deal_ids, linked_company_ids), the provider message_id (pass it as reply_to_message_id with the thread_id to reply through crm.email.send) and the attachments. Not found if the thread is not in the mailbox's latest emails or the mailbox is private to the caller.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:read

Permissão

Ver o módulo · Ação do CRM: view_inbox

Tool do MCP

crm_email_threads_getNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.get".

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

Parâmetros

Resposta

Erros

Exemplo

curl "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads/{thread_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/crm/emails/mailboxes/{owner_user_id}/threads/{thread_id}" \
  -H "Authorization: Bearer $MB_TEST_KEY"

Link every email of a thread to a person

crm.email.threads.link_person

Links every email of a thread to a person (person_id) and to that person's primary company, keeping the links the emails already had, so the conversation shows in the person's timeline. Use it when the automatic match by email failed (the sender wrote from an address the person does not have). Idempotent. Requires being able to read the mailbox; a seller with restricted scope can only link persons they can see.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_email_threads_link_personNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.link_person".

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

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads/{thread_id}/link-person" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "PERSON_ID"
}'

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/crm/emails/mailboxes/{owner_user_id}/threads/{thread_id}/link-person" \
  -H "Authorization: Bearer $MB_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "PERSON_ID"
}'

Archive an email thread

crm.email.threads.archive

Archives a thread of a mailbox: it leaves the inbox for everyone who reads that mailbox and moves to the archived folder; for Gmail mailboxes it is also archived in Gmail (best effort). It deletes nothing; crm.email.threads.unarchive brings it back. Idempotent. Requires being able to read the mailbox.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_email_threads_archiveNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.archive".

Custo declarado: até 501 leituras e 500 escritas por chamada (contam na cota diária). Usa uma plataforma externa (gmail): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads/{thread_id}/archive" \
  -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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Move an archived email thread back to the inbox

crm.email.threads.unarchive

Moves an archived thread of a mailbox back to the inbox for everyone who reads that mailbox (and back to the Gmail inbox, best effort). Idempotent. Requires being able to read the mailbox.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_email_threads_unarchiveNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.unarchive".

Custo declarado: até 501 leituras e 500 escritas por chamada (contam na cota diária). Usa uma plataforma externa (gmail): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads/{thread_id}/unarchive" \
  -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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Archive many email threads of a mailbox

crm.email.threads.archive.bulk

Archives up to 50 threads of one mailbox at once (same effect as archiving them one by one, also in Gmail, best effort). Requires being able to read the mailbox. Bulk: outside the screen it requires a dry run and a confirm_token.

Pede confirmação: primeiro dry_run: true (prévia e confirm_token, válido por 10 minutos e por uma única execução), depois o mesmo corpo com confirm_token. Em algumas poucas, só com certos dados: a descrição diz quando. Por que e como: Prévia e confirmação.

Só se a organização permitir e a credencial tiver isso concedido; devolve só o vinculado ao CRM da própria caixa. E-mail e calendário conectados

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_email_threads_archive_bulkNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.threads.archive.bulk".

Custo declarado: até 501 leituras e 500 escritas por chamada (contam na cota diária). Usa uma plataforma externa (gmail): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/threads/bulk/archive" \
  -H "Authorization: Bearer $MB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "thread_ids": [
    "THREAD_ID"
  ],
  "dry_run": true
}'

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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.

Sync a mailbox now

crm.email.mailbox.sync

Pulls the new messages of a mailbox from its provider (Gmail, Outlook or IMAP) since its last sync (the last 90 days the first time, up to 2,000 messages) and records the ones that match CRM persons or companies as email activities, with the same deduplicated ingestion as the scheduled sync: running it again never duplicates. Returns how many were fetched, recorded and skipped (and why). It can take tens of seconds. Requires being able to read the mailbox.

Escopo

crm:write

Permissão

Editar no módulo

Tool do MCP

crm_email_mailbox_syncNa superfície completa; na compacta, mb_execute_operation com id: "crm.email.mailbox.sync".

Custo declarado: até 2002 leituras e 2001 escritas por chamada (contam na cota diária). Usa uma plataforma externa (gmail): conta na cota de operações externas.

Parâmetros

Resposta

Erros

Exemplo

curl -X POST "https://api.mb-suite.com/v1/crm/emails/mailboxes/{owner_user_id}/sync" \
  -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. Na prática esta operação não é simulada (usa outra plataforma): responde 409 sandbox_external_unavailable.