Endereços Enviar como via API e MCP

O TrekMail separa duas tarefas que usam credenciais e permissões diferentes:

1. A interface Painel/Ops controla perfis SMTP reutilizáveis e o roteamento de domínios. Ela usa um token tm_live_ com smtp:read ou smtp:write.
2. A interface Webmail/Mensagens controla os endereços de remetente disponíveis para uma caixa e uma caixa de entrada conectada. Ela usa um token tm_msg_ com messages:read, messages:write ou messages:send.

Essa separação é intencional. Um token de caixa pode selecionar uma rota de envio já autorizada, mas não pode revelar credenciais SMTP nem gerenciar a infraestrutura de outra conta.

Resumo

• Se você enviar apenas com external_account_id, os destinatários verão o endereço próprio dessa conta conectada e o servidor SMTP dela será usado.
• Se você também enviar um identity_id vinculado à origem, os destinatários verão o endereço comercial da identidade. O TrekMail usa a rota do domínio ou o perfil SMTP salvo atribuído a essa identidade e depois salva a cópia em Enviados na caixa conectada.
• O Starter permite configurar e usar isso no webmail. Pro e Agency também permitem automatizar pela API ou pelo MCP. O Nano não oferece espaços para contas conectadas.

As ferramentas disponíveis de API e MCP evoluem com o produto. Enviar como usa as famílias SMTP e de mensagens, e cada conexão vê apenas o subconjunto permitido pelo plano, pelos escopos e pelas permissões aprovadas.

Modelo de roteamento

Quando external_account_id é enviado sem identity_id, o TrekMail envia pelo servidor SMTP da própria conta externa e usa o endereço dela.

Quando os dois valores são enviados, o TrekMail trata a conta externa como o destino da caixa de entrada/Enviados e a identidade como o remetente visível + rota SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

A identidade e a conta externa precisam estar vinculadas. Omitir a origem ou fornecer uma identidade de outra caixa retorna 422 identity_unavailable.

1. Inspecionar ou configurar SMTP na API do painel

Use um token de Ops.

As leituras de perfil nunca retornam a senha. O endpoint de uso é a maneira segura de um agente explicar o impacto antes de editar ou excluir um perfil compartilhado.

Ferramentas MCP: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. Listar endereços para a caixa de entrada exata

Use um token de Mensagens:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

A resposta inclui identities específicas da origem, todas as external_identities configuradas, sending_addresses, os send_as_domains qualificados, a reply_from_policy da caixa e, apenas para a caixa do proprietário da conta, smtp_profiles salvos que podem ser selecionados diretamente.

MCP: chame list_identities com external_account_id.

MCP hospedado e stdio local

As ferramentas de mensagens têm uma diferença importante de transporte:

• MCP HTTP hospedado (OAuth): também forneça mailbox_id em cada chamada de ferramenta de mensagens. O servidor hospedado usa esse valor para provisionar um token de mensagens de curta duração para a caixa exata. Por exemplo, chame list_identities com { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio auto-hospedado (tm_msg_): não forneça mailbox_id. O token de mensagens estático já está vinculado a uma caixa, então o esquema da ferramenta precisa apenas de external_account_id.

external_account_id nunca substitui mailbox_id: ele seleciona uma caixa de entrada conectada dentro da caixa já autorizada. As ferramentas SMTP do painel continuam limitadas à conta e não recebem mailbox_id em nenhum dos transportes.

3. Criar uma identidade Enviar como

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email já deve ser o endereço principal desta caixa ou um alias ativo habilitado para envio. O domínio deve estar ativo e pertencer à mesma conta. smtp_mode: domain segue a rota de domínio configurada no painel. smtp_mode: profile fixa a identidade em smtp_connection_id; a seleção direta de perfil é limitada à caixa do proprietário da conta.

external_account_id é opcional, e vale a pena esclarecer o significado:

• Inclua-o ao ler as mensagens desse endereço por uma caixa de entrada conectada do Gmail, Outlook ou IMAP. A identidade fica vinculada a essa caixa e só pode ser usada com ela.
• Omita-o quando as mensagens forem encaminhadas para uma caixa do TrekMail, no fluxo de caixa compartilhada em que um cliente mantém as mensagens no próprio provedor e encaminha cópias para uma caixa da equipe. A identidade pertence à própria caixa e todos os membros com permissão de envio podem usá-la.

Uma caixa de entrada pessoal conectada nunca pode ser associada a uma caixa compartilhada: ela é privada para a pessoa que a conectou. Nesse caso, omita external_account_id.

MCP: create_identity com kind=send_as. No MCP hospedado, inclua o mailbox_id pai conforme descrito acima.

4. Enviar, criar rascunho, agendar, responder ou encaminhar

As operações comuns de mensagens aceitam o mesmo par de origem:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id é compatível com envio imediato, salvamento/atualização de rascunhos e envio agendado. A preparação de respostas/encaminhamentos aceita external_account_id e seleciona a identidade correspondente nos cabeçalhos de entrega. A identidade selecionada é autorizada novamente quando uma mensagem na fila é executada; desativar seu alias, domínio, perfil ou conta conectada interrompe a entrega em vez de usar silenciosamente outro endereço de remetente.

Ferramentas MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all e prepare_forward.

Política de resposta

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient responde usando o endereço que recebeu a mensagem quando possível. default sempre começa com o padrão da caixa para mensagens normais. O MCP usa set_reply_from_policy.

Regras de segurança e isolamento

• As credenciais SMTP nunca aparecem na resposta da API de mensagens ou do MCP.
• Toda conta externa e identidade é limitada à caixa do token de mensagens.
• Uma identidade Enviar como conectada só pode ser usada com seu external_account_id exato; uma identidade pertencente à caixa só pode ser usada sem ele.
• O endereço de remetente já deve estar autorizado como endereço da caixa ou alias habilitado para envio; a API não pode inventar endereços de remetente arbitrários.
• Uma rota funcional é exigida antes da criação e verificada novamente na entrega.
• Cabeçalhos Reply-To personalizados não podem entrar em conflito com o Reply-To salvo de uma identidade.
• Alterações de identidade e perfil pelo MCP exigem a permissão de gravação apropriada. Um administrador MCP hospedado localmente pode exigir aprovação explícita para ações de gravação; o envio também exige confirmação por mensagem.

Não são necessárias novas strings de escopo de token. Os tokens smtp:* e messages:* existentes continuam funcionando de acordo com suas permissões atuais.

Qual limite de envio se aplica?

As chamadas de API também mantêm suas próprias proteções contra abuso: por padrão, 60 solicitações de envio por minuto por token de mensagens e 100 envios de API por dia em toda a caixa. Elas se aplicam independentemente do servidor que finalmente entrega o e-mail.