Configurar apps de e-mail via API e MCP

O TrekMail expõe via REST e MCP os mesmos dados de conexão de Aplicativos e dispositivos usados pelo painel. Ambas as interfaces são somente leitura e exigem acesso de leitura à caixa postal.

Elas nunca retornam a senha da caixa, uma senha de app ou credenciais de um provedor SMTP personalizado. O usuário digita uma senha de app diretamente no aplicativo, ou a senha da caixa se ela ainda for aceita. Mesmo quando um domínio encaminha mensagens por um provedor personalizado, aplicativos externos enviam ao endpoint SMTP público do TrekMail; o TrekMail aplica a rota privada do domínio internamente.

Obter configurações de conexão

GET /api/v1/mailboxes/{mailbox_id}/client-setup?lang=en
Authorization: Bearer tm_live_...

Escopo interno obrigatório: mailboxes:read. As restrições opcionais domain_ids e mailbox_ids do token são aplicadas.

A resposta contém:

• host IMAP de entrada, porta SSL, nome de usuário e prontidão;
• host SMTP de saída, porta SSL, nome de usuário e prontidão;
• URL do servidor DAV para calendários e contatos, prontidão da conexão e indicação de marca no endereço retornado;
• os mesmos guias localizados em três etapas para Gmail, Outlook, Apple Mail, Thunderbird e IMAP genérico exibidos em Aplicativos e dispositivos;
• sending.mode: platform, profile ou not_configured;
• sending.reason: motivo estável e legível por máquina quando o envio não está pronto;
• apple_mail_profile.available, que é true somente quando recebimento e envio estão prontos;
• shared_mailboxes.native_access_enabled, namespace, items[];
• authentication.client_auth_mode: app_password_only ou password_or_app_password;
• authentication.accepted_passwords: ["app_password"] ou ["mailbox_password", "app_password"], respectivamente;
• authentication.app_passwords_endpoint: o endpoint de gerenciamento de senhas de app da caixa;
• password_included: false como garantia explícita de segurança.

shared_mailboxes.items[] inclui apenas membros com a permissão Ler quando o acesso nativo a pastas está ativado. delegated_send_addresses é uma lista separada de endereços disponíveis da equipa no campo De com id, email e display_name; pode estar vazia. Não dá acesso a pastas nem verifica se o envio está pronto. Estes endereços não são identidades da Message API. Use os servidores devolvidos, também em White Label, em vez de copiar um servidor da plataforma.

Cada item delegado contém native_access_status/native_access_ready duráveis, caminhos padrão exatos em folders, operations impostas pelo servidor e valores efetivos send_as_ready/send_as_reason. can_send continua sendo a permissão Enviar como atribuída pelo administrador; ela pode ser true enquanto SMTP está indisponível, por isso a automação deve verificar ambos os campos de prontidão. Uma caixa membro inativa, com login suspenso ou login direto desativado permanece visível, mas retorna mailbox_unavailable, mailbox_login_suspended ou direct_login_unavailable como motivo de Enviar como. O campo legado folder mantém o caminho exato da Caixa de entrada. Aguarde native_access_ready=true antes de orientar o usuário.

SMTP transporta uma resposta ou encaminhamento, mas não salva a cópia em Enviados. Portanto, sent_copy.smtp_saves_copy é false; configure o cliente para anexar a cópia a sent_copy.folder (o mesmo valor de folders.sent) para toda a equipe vê-la. folders.archive e folders.junk são destinos exatos quando o cliente não mapeia Arquivo ou Spam automaticamente. Mover para Lixo eletrônico não garante treinamento do classificador de spam do servidor.

Sempre solicite este endpoint com o ID da caixa membro normal e autentique o cliente com o endereço próprio desse membro e uma senha de app, ou a senha da caixa se aceita. Não crie outra conta nem tente autenticação direta com o endereço compartilhado.

A lista de pastas shared_mailboxes descreve o acesso nativo de quem pode ler a caixa. Se items estiver vazio, verifique o acesso nativo e Ler. Uma lista vazia não prova que todo o acesso a endereços compartilhados foi retirado. Nenhuma senha é retornada.

O parâmetro opcional lang aceita os mesmos 13 idiomas do endpoint de perfil Apple. Se omitido, o TrekMail usa Accept-Language e depois a localidade padrão. Cada guia possui id estável, três steps localizadas e uma action: use_server_settings ou download_apple_profile.

connection_status=receiving_only não é uma configuração completa bem-sucedida. Configure ou restaure a rota de saída antes de orientar o usuário a conectar um cliente que valida ambos os servidores.

connection_status=unavailable significa que o ciclo de vida da caixa mudou e ela não pode mais se autenticar diretamente. Não use as coordenadas retornadas nem ofereça um perfil Apple Mail; atualize o estado da caixa.

Baixar um perfil do Apple Mail

GET /api/v1/mailboxes/{mailbox_id}/apple-mail-profile?lang=en
Authorization: Bearer tm_live_...
Accept: application/x-apple-aspen-config

A resposta é um anexo .mobileconfig. Os valores de lang aceitos são en, es, fr, de, pt, it, nl, ru, zh, ja, ko, ar e he. Se lang for omitido, o TrekMail usa Accept-Language e depois a localidade padrão.

O perfil contém configurações IMAP e SMTP, mas nenhum campo de senha. A Apple solicita uma senha durante a instalação: use uma senha de app para app_password_only ou qualquer senha aceita para password_or_app_password. O TrekMail retorna 409 mail_client_setup_not_ready em vez de gerar um perfil enganoso enquanto o envio está indisponível.

Crie uma senha de app no webmail em Configurações, Senhas de app ou no painel em Caixas de e-mail, (caixa), Segurança, Senhas de app. O endpoint de configuração, somente de leitura, não cria senhas. Para endpoints REST e ferramentas MCP que gerenciam essas senhas e o modo de acesso, consulte Senhas de app via API e MCP.

Ferramentas MCP

As ferramentas usam os mesmos endpoints REST e regras de autorização:

Os transportes MCP retornam conteúdo estruturado em vez de download do navegador. Decodifique content_base64 como bytes e salve usando file_name; não o interprete como JSON ou UTF-8 antes da decodificação.

Ambas exigem o escopo OAuth hospedado mail:read, que se expande para mailboxes:read. Elas são somente leitura e não dependem de variável de ambiente para operações destrutivas no servidor stdio auto-hospedado.

Erros

O endpoint pode retornar estes valores de sending.reason: mailbox_unavailable, direct_login_unavailable, domain_unavailable, domain_deprovisioning, account_suspended, email_verification_required, mailbox_sending_disabled, smtp_not_configured, managed_smtp_not_in_plan, managed_smtp_entitlement_inactive, smtp_profile_unavailable ou smtp_route_invalid.