Contas conectadas via API e MCP

As contas conectadas permitem que uma caixa de webmail leia e envie mensagens de caixas externas, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 ou qualquer servidor IMAP. A API de mensagens e as ferramentas MCP oferecem a mesma capacidade de forma programática: você pode listar, adicionar, testar, editar e remover contas conectadas, além de direcionar chamadas comuns de mensagens (listar, ler, enviar, sinalizadores, mover, excluir e pastas) para uma conta conectada em vez da caixa do próprio token.

Em termos simples: mailbox_id escolhe a caixa do TrekMail pela qual o agente pode atuar, enquanto external_account_id escolhe o Gmail ou outra caixa conectada dentro dela. Eles não são intercambiáveis.

Planos, limites e tamanho do catálogo

O gerenciamento de contas conectadas oferece sete ferramentas de mensagens. Um token com escopo limitado vê apenas as ferramentas que pode realmente usar, e não o catálogo completo do produto.

Antes de começar

• As contas conectadas são um recurso de webmail e usam a interface de token de mensagens (/api/v1/messages/...), autorizada por um token de mensagens com os escopos abaixo, e não por um token de API do painel.
• Os limites do plano são aplicados por caixa: Starter 5, Pro 10, Agency 30. O plano Nano não inclui contas conectadas.
• Cada endpoint é limitado à própria caixa do token. Um token só pode ver e gerenciar suas próprias contas conectadas, nunca as de outra caixa.
• Credenciais e tokens OAuth são sempre mascarados nas respostas. Você pode inserir uma senha ou senha de aplicativo, mas nunca pode consultá-la novamente.
• Contas do Outlook.com e do Microsoft 365 são conectadas pelo login da Microsoft (OAuth) na interface do webmail. A API pode gerenciá-las e usá-las após a conexão, mas não realiza a etapa interativa de consentimento da Microsoft.

Escopos

Direcionar uma chamada de mensagens para uma conta conectada exige o mesmo escopo que a chamada já requer (por exemplo, listar suas mensagens exige messages:read; enviar exige messages:send).

Gerenciamento de contas conectadas

Caminho base: /api/v1/messages/external-accounts

Adicionar uma conta

POST /api/v1/messages/external-accounts
Scope: messages:write

Corpo da solicitação:

Primeiro, chame POST /external-accounts/detect para preencher provider e as configurações do servidor automaticamente. A chamada de armazenamento executa um teste real de IMAP + SMTP antes de salvar. Um 422 com uma categoria de erro (auth, tls, network, transient_throttle) significa que as credenciais não funcionaram e nada foi armazenado.

Direcionamento de uma conta conectada nas chamadas de mensagens

Todo endpoint de mensagens que opera em uma caixa aceita um external_account_id opcional. Forneça-o para executar a chamada nessa conta conectada em vez da caixa do próprio token; omita-o para usar a própria caixa. Isso se aplica a listar, ler, enviar, responder, definir sinalizadores, mover e excluir mensagens, além de listar pastas.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

O envio apenas com external_account_id usa o próprio servidor SMTP da conta (com SPF/DKIM do provedor). Fornecer um identity_id vinculado à origem usa o domínio ou a rota do perfil salvo dessa identidade Enviar como, mas ainda salva a cópia em Enviados na caixa conectada. A conta deve estar íntegra (status: active); uma conta desconectada retorna um erro solicitando que você a reconecte. Consulte Endereços Enviar como via API e MCP.

Ferramentas MCP

A mesma capacidade está disponível para agentes de IA via MCP (tanto no servidor stdio privado quanto no servidor MCP público):

As ferramentas de mensagens list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all e prepare_forward aceitam o argumento opcional external_account_id. Enviar, criar rascunhos e agendar também aceitam um identity_id vinculado à origem retornado por list_identities.

Como as ferramentas de gerenciamento abrem conexões de saída com servidores de e-mail arbitrários usando credenciais fornecidas pelo usuário, elas seguem a mesma postura de segurança do restante do recurso de contas conectadas: lista de hosts permitidos, bloqueio de intervalos privados, lista de portas permitidas e limites de conexão por host.