Configuração de cliente 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 ou credenciais de um provedor SMTP personalizado. O usuário digita a senha diretamente no aplicativo. 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 configurado e uma entrada items[] para cada caixa compartilhada delegada a esta caixa normal;
• password_included: false como garantia explícita de segurança.

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 Pode responder 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 endereço e senha próprios desse membro. Não crie outra conta nem tente autenticação direta com o endereço compartilhado.

Quando o acesso nativo está desativado, shared_mailboxes.native_access_enabled é false e items fica vazio. Quando está ativado, mas items está vazio, a caixa normal não possui associação ativa a caixas compartilhadas. Nenhuma senha é incluída em ambos os casos.

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 a senha durante a instalação. O TrekMail retorna 409 mail_client_setup_not_ready em vez de gerar um perfil enganoso enquanto o envio está indisponível.

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.