Senhas de app para caixas via API e MCP

A API REST e o MCP podem listar, criar, substituir e revogar senhas de app de uma caixa comum, alterar seu modo de acesso de apps de e-mail e definir o padrão da conta para caixas futuras. Esta página é a referência para integrações. Para instruções do painel e webmail, consulte Senhas de app para seus dispositivos.

Uma senha de app permite acesso por IMAP, SMTP nas portas 465 e 587, ManageSieve e CalDAV/CardDAV. Ela nunca abre o novo webmail nem o painel. O webmail clássico entra por IMAP e aceita senhas de app. A 2FA da caixa protege apenas o login no novo webmail; apps de e-mail e o webmail clássico nunca pedem seu código.

O recurso não tem uma restrição adicional de plano para caixas. As permissões de plano existentes da API e do MCP continuam valendo; consulte Escopos e permissões da API.

Autenticação, escopos e permissões de membros

Use um token Bearer nas solicitações REST em /api/v1. Solicitações de gravação em JSON usam Content-Type: application/json e um cabeçalho Idempotency-Key.

A permissão para definir senhas é verificada na função do membro, além do escopo de API do token. Isso vale para tokens de membros e conectores autorizados por membros. Um token do proprietário não precisa de um escopo adicional para definir senhas. Se faltar a permissão do membro, o retorno é 403 scope_blocked_by_membership.

Conectores OAuth hospedados podem usar os escopos de capacidade REST correspondentes. Nos conjuntos legados, mail:read fornece mailboxes:read e account:read; mail:write também fornece mailboxes:write. A expansão de escopos nunca substitui as regras de permissão de membros nem as restrições ao proprietário.

As restrições domain_ids e mailbox_ids do token se aplicam, inclusive a seleções em massa. Os endpoints de senhas de app e os dois endpoints de modo retornam 404 not_found enquanto o recurso estiver desativado, após as verificações de autenticação e middleware. Uma caixa inacessível ou inexistente também retorna 404, então não interprete todo 404 como indicação do estado do recurso.

Endpoints em resumo

Os caminhos abaixo incluem o prefixo /api/v1. {mailbox} é o ID da caixa comum; {id} é o ID de uma entrada de senha de app pertencente a ela.

Todas as gravações desta tabela exigem Idempotency-Key. O endpoint de senha é uma operação de redefinição administrativa existente, separada da substituição de senhas de app.

Listar senhas de app e entender os campos de cada entrada

GET /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token

A resposta contém mailbox_id, client_auth_mode, limit, active_count e data, um array de entradas, no nível superior. limit é de 25 senhas ativas por caixa. Entradas ativas aparecem primeiro, das mais recentes para as mais antigas; entradas revogadas continuam visíveis por 90 dias. Nenhuma resposta de listagem contém uma senha.

Cada entrada contém:

Os motivos públicos de revogação são revoked, rotated, mailbox_password_reset, mailbox_password_changed, login_suspended, converted_to_shared e mailbox_trashed. A lista exclui credenciais geradas internamente pela plataforma.

Criar uma senha de app

POST /api/v1/mailboxes/42/app-passwords
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: app-password-42-office-pc-001

{"name":"Outlook on the office PC"}

name é obrigatório: de 1 a 64 caracteres imprimíveis. Sequências de espaços em branco são reduzidas a um único espaço. A caixa precisa ser comum e ativa, sem suspensão de acesso, e ter menos de 25 senhas de app ativas.

A resposta 201 contém a entrada completa em data, acrescenta data.password e inclui message. Por exemplo, estes são os campos de credenciais dessa resposta:

{
  "data": {
    "id": 81,
    "mailbox_id": 42,
    "name": "Outlook on the office PC",
    "password": "abcdefghijklmnop"
  },
  "message": "Shown once. Use it as the password in the mail app; it does not open webmail."
}

Este exemplo omite os outros campos do registro descritos acima. A senha do exemplo é ilustrativa. Uma senha real tem 16 letras minúsculas geradas, retornadas sem espaços. Apps também aceitam espaços e maiúsculas; exiba-a em quatro grupos de quatro se for apresentá-la a um usuário.

A senha é retornada uma única vez. Não a inclua nos logs do aplicativo. O usuário a digita diretamente no app de e-mail com o endereço completo da caixa como nome de usuário. Criar e substituir enviam uma notificação com o nome da senha de app para a caixa e seu endereço de recuperação, se definido, sem a senha. A primeira senha de app emitida com uma nova caixa é a exceção (veja abaixo).

Use a API de configuração de clientes de e-mail para obter as configurações de conexão. Um perfil Apple baixado não contém senha; o usuário fornece a senha de app quando o macOS ou iOS a solicita durante a instalação.

Receber a primeira senha de app com uma nova caixa

POST /api/v1/mailboxes e POST /api/v1/mailboxes:bulk aceitam um booleano opcional create_app_password. Com true, cada caixa criada também recebe sua primeira senha de app, retornada uma única vez como app_password: os campos do registro descritos acima mais password. Ela se chama Created with the mailbox, e nenhum e-mail de notificação é enviado sobre ela, porque a caixa é nova e quem fez a chamada acabou de receber a senha dela. Sem o campo (padrão false), a resposta não muda. Ele é ignorado enquanto as senhas de app não estiverem ativadas.

POST /api/v1/mailboxes
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: create-alice-001

{"domain_id":7,"local_part":"alice","password_mode":"generated_one_time","client_auth_mode":"app_password_only","create_app_password":true}

A resposta 201 então traz one_time_password, a senha da caixa para o webmail, e app_password.password para os apps de e-mail. Em uma resposta em massa, cada linha criada tem seu próprio app_password. Se ela não pôde ser emitida, app_password é null (a criação individual também adiciona _app_password_warning); a caixa é criada mesmo assim, e você pode criar uma com o endpoint acima. Uma repetição exata de uma criação individual com a mesma Idempotency-Key retorna a mesma resposta, com as duas senhas incluídas, sem emitir uma segunda senha de app. Uma repetição em massa omite as senhas, como faz com one_time_password.

Substituir ou revogar uma senha

A substituição não exige um corpo JSON:

POST /api/v1/mailboxes/42/app-passwords/81:rotate
Authorization: Bearer tm_live_your_token
Idempotency-Key: replace-app-password-81-001

A resposta 200 contém a nova entrada completa em data, seu data.password retornado uma única vez, replaced_id no nível superior identificando a entrada antiga e message. A substituta tem um novo data.id e o mesmo nome. A entrada antiga é revogada com revoked_reason: "rotated", sua senha deixa de funcionar imediatamente e os apps que a usam são desconectados. Atualize o dispositivo com a substituta.

Para revogar sem emitir uma substituta:

DELETE /api/v1/mailboxes/42/app-passwords/82
Authorization: Bearer tm_live_your_token
Idempotency-Key: revoke-app-password-82-001

Nenhum corpo é necessário. A resposta 200 tem status: "revoked" e a entrada revogada completa em data. O app perde o acesso; outros dispositivos com senhas de app válidas se reconectam sozinhos. A revogação não pode ser desfeita. Tentar substituir ou revogar uma entrada já revogada com uma nova solicitação retorna 409 conflict.

Alterar o modo de acesso de apps de e-mail de uma caixa

POST /api/v1/mailboxes/42:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-42-001

{"mode":"app_password_only"}

mode é obrigatório e aceita:

• app_password_only: apps de e-mail exigem uma senha de app. Conexões que usam a senha da caixa são desconectadas; apps com uma senha de app válida se reconectam sozinhos.
• password_or_app_password: apps de e-mail aceitam a senha da caixa ou uma senha de app.

A resposta 200 tem mailbox_id, client_auth_mode e message. Definir novamente o modo atual retorna 200 e não muda nada. Alterar o modo não revoga senhas de app existentes.

Crie senhas para os dispositivos antes de torná-las obrigatórias. Um login recusado com a senha da caixa pode mostrar: "Sign-in failed. This mailbox accepts app passwords only: create one in webmail under Settings > App passwords." (Falha no login. Esta caixa aceita somente senhas de app: crie uma no webmail em Configurações > Senhas de app.) Alguns apps mostram apenas um erro genérico de senha.

Caixas compartilhadas não têm login direto e retornam 422 mailbox_not_eligible neste endpoint. Caixas de sistema da plataforma não podem ser alteradas para app_password_only; isso retorna 422 system_mailbox_protected.

Nenhum modo muda o login no novo webmail, Todas as caixas de entrada, tokens da API de mensagens, migrações para a caixa, regras de e-mail ou encaminhamento. Membros de caixas compartilhadas usam as credenciais e o modo de suas próprias caixas comuns.

Alterar modos em massa

POST /api/v1/mailboxes:client-auth-mode
Authorization: Bearer tm_live_your_token
Content-Type: application/json
Idempotency-Key: require-app-passwords-domain-7-001

{"domain_id":7,"mode":"app_password_only"}

Forneça mode e exatamente um seletor:

Restrições da conta e do token limitam toda seleção. Um ID explícito fora do acesso, ou desconhecido, retorna 404 em vez de aplicar uma seleção parcial. Um domínio desconhecido ou de outra conta retorna 422 validation_error. Nenhum seletor ou vários seletores retornam 422 invalid_selection.

No máximo 1000 caixas podem corresponder à seleção. Uma seleção maior retorna 422 selection_too_large antes de qualquer alteração. Restrinja a seleção por domínio ou envie lotes explícitos.

{
  "data": {
    "client_auth_mode": "app_password_only",
    "matched": 24,
    "updated": 21,
    "skipped": 3
  }
}

matched conta as caixas selecionadas; updated conta mudanças reais de modo; skipped conta caixas compartilhadas, na lixeira ou em processo de exclusão, além de caixas de sistema da plataforma quando senhas de app são exigidas. Caixas pausadas ou com acesso suspenso podem ter seu modo atualizado para quando o acesso voltar. Caixas que já estão no modo desejado contam como correspondentes, mas não como atualizadas nem ignoradas, então é seguro repetir a operação. Contas suspensas são recusadas com 403.

Ler o estado das caixas e definir o padrão da conta

Enquanto senhas de app estiverem ativadas, GET /api/v1/mailboxes e GET /api/v1/mailboxes/{mailbox} incluem estes campos nos recursos de caixas:

• client_auth_mode: app_password_only ou password_or_app_password.
• app_passwords_count: contagem inteira de senhas de app ativas visíveis, excluindo credenciais internas da plataforma.

Os dois campos são omitidos enquanto o recurso estiver desativado. Caixas compartilhadas não têm modo de login direto utilizável nem senhas de app; solicite credenciais para uma caixa comum de membro.

GET /api/v1/account exige account:read. Seus campos normais no nível superior continuam disponíveis: id, name, email, plan, effective_plan_slug, subscription_status, limits, features, usage, safety_limits e created_at. Ele acrescenta new_mailbox_client_auth_mode somente quando senhas de app estão ativadas e a plataforma aplica o padrão da conta a novas caixas. Caso contrário, GET continua disponível e omite esse campo.

Somente o proprietário da conta pode alterar o padrão:

PATCH /api/v1/account
Authorization: Bearer tm_live_owner_token
Content-Type: application/json
Idempotency-Key: new-mailbox-default-001

{"new_mailbox_client_auth_mode":"app_password_only"}

O campo obrigatório aceita os mesmos dois modos. Este é o único campo de conta gravável aqui. A resposta tem id, new_mailbox_client_auth_mode e message no nível superior. PATCH retorna 404 se as duas condições para expor o campo não forem atendidas, e 403 scope_blocked_by_membership para qualquer token de membro ou conector autorizado por membro.

Um token do proprietário limitado por domain_ids ou mailbox_ids retorna 403 token_resource_constrained. Use um token do proprietário sem restrições de recursos ou altere o padrão nas configurações da conta.

O padrão afeta caixas futuras criadas no painel, em massa, por convites, pela API e por agentes. Ele nunca muda caixas existentes. A criação individual de uma caixa pela API pode fornecer client_auth_mode explicitamente em POST /api/v1/mailboxes; omiti-lo segue o padrão da conta. Caixas existentes mantêm password_or_app_password quando o recurso é lançado. O padrão para novas caixas é app_password_only, a menos que o proprietário da conta o altere.

Redefinir a senha da caixa revoga senhas de app automaticamente

POST /api/v1/mailboxes/{mailbox}/password exige mailboxes:write, a mesma permissão de membro para definir senhas e Idempotency-Key. Seu corpo exige password, a nova senha da caixa, de acordo com a política de senhas de caixas. Este não é um endpoint de criação de senha de app.

Toda redefinição administrativa bem-sucedida por este endpoint, inclusive uma alteração de senha por agente MCP, revoga todas as senhas de app com o motivo mailbox_password_reset. Não há opção de manter as senhas. Enquanto o recurso estiver ativado, a resposta inclui app_passwords_revoked, uma contagem inteira, junto com status, sync_pending e message:

• 200, status: "updated", sync_pending: false quando a sincronização do servidor de e-mail foi concluída.
• 202, status: "update_pending", sync_pending: true quando a senha foi salva e a sincronização está pendente. As senhas de app já estão revogadas nesse momento.

A redefinição também revoga tokens de mensagens existentes da caixa. Isso é consequência de redefinir a senha da caixa, não de substituir uma senha de app individual nem de alterar o modo de apps de e-mail.

Alterações de senha pelo próprio usuário no webmail só revogam senhas de app quando ele seleciona Revogar também todas as senhas de app. Recuperação de senha, suspensão do acesso, conversão para caixa compartilhada e mudança para Excluídos recentemente revogam todas. Restaurar o acesso ou a caixa não restaura senhas revogadas. Consulte Suspender o login da caixa por API.

Idempotência e senhas retornadas uma única vez

Use um novo Idempotency-Key para cada gravação intencional e reutilize-o apenas para repetir a mesma solicitação após uma falha de transporte, com o mesmo método, caminho e corpo. Chaves são obrigatórias e podem ter no máximo 255 caracteres. Respostas bem-sucedidas são armazenadas em cache pela janela padrão de 24 horas; reutilizar uma chave para uma solicitação diferente retorna 409 idempotency_mismatch.

Uma repetição idempotente de criação ou substituição de senha de app retorna os mesmos identificadores seguros, mas omite data.password. Ela inclui _idempotency_replay_warning e o cabeçalho de resposta X-Idempotency-Replayed: true. Uma repetição não recupera uma senha perdida. Use o data.id retornado para substituir a entrada ativa com uma nova chave e obter uma senha utilizável. Registre o novo ID após a substituição.

Repetir uma revogação bem-sucedida com a mesma chave retorna seu resultado salvo. Uma nova solicitação de revogação para aquela entrada revogada retorna 409 conflict. Mudanças de modo são naturalmente repetíveis, mas dê uma nova chave a cada alteração intencional: reutilizar uma chave anterior depois de mudar de modo pode repetir uma resposta antiga em vez de aplicar sua nova intenção.

Limites de taxa e erros

A criação é limitada a 60 por hora por conta, e a substituição a 30 por hora por conta. Esses limites da conta são compartilhados por chamadas da API e do MCP, sem cotas separadas por token. Mudanças de modo em massa têm um limite adicional de 10 solicitações por minuto. O limitador normal da API também vale para essas rotas; seu padrão é de 60 solicitações por minuto por credencial. Uma solicitação limitada retorna 429 rate_limited; respeite o cabeçalho Retry-After antes de tentar novamente.

Erros usam o objeto error padrão com code, message, hint, request_id e retryable. Trate o código legível por máquina em vez de comparar o texto da mensagem.

Ferramentas MCP e controle de ações destrutivas

O MCP usa a mesma autorização e os mesmos campos de resposta do REST. As ferramentas diretas são:

As ferramentas de criação de caixas create_mailbox_generated_password e bulk_create_mailboxes aceitam a mesma entrada opcional create_app_password do REST.

Ferramentas de gravação também aceitam idempotency_key opcional. REST usa o campo mode no corpo para mudanças de modo de caixas; a ferramenta MCP chama essa entrada de client_auth_mode. Seus seletores em massa têm as mesmas regras de acesso e o mesmo limite de 1000 caixas do REST.

list_mailbox_app_passwords(mailbox_id=42)
create_mailbox_app_password(mailbox_id=42, name="Outlook on the office PC")
rotate_mailbox_app_password(mailbox_id=42, app_password_id=81)
revoke_mailbox_app_password(mailbox_id=42, app_password_id=82)
set_mailbox_client_auth_mode(mailbox_id=42, client_auth_mode="app_password_only")
set_mailbox_client_auth_mode(domain_id=7, client_auth_mode="app_password_only")
update_account(new_mailbox_client_auth_mode="app_password_only")

No servidor com hospedagem própria, toda gravação acima exige TREKMAIL_ALLOW_DESTRUCTIVE=true. Criar uma credencial também exige essa liberação, pois concede acesso à caixa. Listagens e leituras da conta não exigem essa opção. Peça ao usuário aprovação para a alteração pretendida de credencial ou acesso antes de executar uma gravação. Ferramentas diretas que retornam senhas instruem o agente a mostrá-las uma única vez, pedir ao usuário que as cole no app e nunca salvá-las em arquivos ou memória nem repeti-las em mensagens ou chamadas de ferramentas posteriores.

Perfis dos diretórios do ChatGPT/OpenAI e Claude

Esses perfis fornecem um link seguro de configuração no painel para criação e substituição, em vez de gerar uma senha no chat. A criação de caixas ali também é um link para o painel, então a primeira senha de app vem do cartão Caixa criada do painel, não de create_app_password. O destino é /app/mailboxes/{mailbox_id}/security#app-passwords; o usuário entra e conclui a ação ali.

O perfil OpenAI expõe get_mailbox_app_password_setup_link e get_mailbox_app_password_replacement_setup_link. O perfil Claude mantém os nomes create_mailbox_app_password e rotate_mailbox_app_password, mas retorna o link seguro de configuração em vez de data.password. Não prometa uma senha por essas ferramentas de diretório nem peça ao usuário que cole uma na conversa.

Para dados de conexão, use get_mail_client_setup. Para configuração geral de conectores, consulte Conectar agentes de IA. Caixas White Label usam o mesmo recurso da API e hosts de webmail e e-mail da marca; chame a credencial de senha de app nas instruções para usuários.