Suspender o login da caixa por API

Suspender o login impede que uma pessoa entre em uma caixa de correio, enquanto a própria caixa continua funcionando. As mensagens são entregues normalmente e ficam esperando; nada é devolvido nem perdido. Esta página é a referência dos comandos para configurar essa opção.

O mesmo controle fica no painel, em Caixas de correio → (uma caixa) → Limites. Ele está disponível em todos os planos sem custo adicional.

Suspender ou pausar: são chamadas diferentes

Use :suspend-login para um cliente que não pagou, uma pessoa entre contratos ou qualquer pessoa cujas mensagens você ainda queira receber. Use :pause quando a caixa de correio precisar parar completamente, inclusive para os remetentes.

Existe um terceiro estado que nenhuma dessas chamadas alcança. Se a atividade de saída sugerir que a senha de uma caixa foi usada indevidamente, a TrekMail pode impedir o envio dessa caixa e manter o login e a entrega inalterados. Os envios passam a retornar 403 mailbox_sending_paused. Nem :resume nem :resume-login removem esse estado, e repetir a chamada também não: é preciso alterar a senha e o suporte reativa o envio. Consulte Por que não consigo enviar e-mails?.

Escopo necessário

mailboxes:write, o mesmo escopo que atualiza qualquer outro campo da caixa. Todos os endpoints abaixo aceitam um cabeçalho Idempotency-Key.

Uma caixa de correio

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:suspend-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-{MAILBOX_ID}-invoice-42" \
  -d '{"reason":"Unpaid invoice 42"}'

{ "status": "login_suspended", "message": "Sign-in has been suspended. The mailbox keeps receiving mail." }

reason é opcional e aceita até 255 caracteres. O motivo aparece no seu painel e é retornado pela API; o usuário suspenso nunca o vê.

Para remover a suspensão:

curl -s -X POST "https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}:resume-login" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Idempotency-Key: resume-{MAILBOX_ID}"

Consultar o estado

Tanto GET /api/v1/mailboxes/{id} quanto o endpoint de listagem incluem o estado, para que você possa fazer uma auditoria sem alterar nada:

{ "data": { "id": 1701, "email": "sam@example.com", "status": "active",
            "login_suspended": true,
            "login_suspended_at": "2026-08-16T14:02:11+00:00",
            "login_suspended_reason": "Unpaid invoice 42", "...": "..." } }

Observe que status continua sendo active. Isso não é um erro a contornar: a caixa está ativa e recebendo mensagens. Leia login_suspended para o login e status para saber se a própria caixa está em funcionamento.

Várias caixas de uma vez

curl -s -X POST "https://trekmail.net/api/v1/mailboxes:login-access" \
  -H "Authorization: Bearer tm_live_your_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: suspend-domain-123-august" \
  -d '{"domain_id":123,"login_suspended":true,"reason":"Unpaid invoice 42"}'

Passe exatamente um seletor:

A resposta informa o que aconteceu:

{ "data": { "login_suspended": true, "matched": 24, "updated": 21, "skipped": 3 } }

matched é o número de caixas encontradas pelo seletor, updated é quantas realmente mudaram e skipped é o número de caixas às quais não foi possível aplicar a chamada. As caixas que já estão no estado solicitado são encontradas, mas não atualizadas. Portanto, é seguro repetir a chamada, o que é útil se uma tarefa de cobrança a executar todas as noites.

Defina "login_suspended": false para restaurar o mesmo conjunto.

Com um agente MCP

suspend_mailbox_login(mailbox_id=1701, reason="Unpaid invoice 42")
resume_mailbox_login(mailbox_id=1701)
set_mailboxes_login_access(domain_id=123, login_suspended=true, reason="Unpaid invoice 42")

As três ferramentas estão disponíveis para um agente com o escopo necessário. Em um servidor MCP hospedado localmente, o administrador pode exigir aprovação explícita para ações de gravação, o que impede um agente de bloquear usuários por acidente.

O que uma caixa suspensa faz

A suspensão é aplicada em todos os pontos de entrada, não fica apenas oculta na interface:

• o login no webmail é recusado, e qualquer sessão já aberta é encerrada
• a autenticação IMAP, POP e SMTP é recusada, portanto os aplicativos de e-mail deixam de funcionar e nada pode ser enviado
• CalDAV e CardDAV são recusados, portanto o calendário e os contatos deixam de sincronizar com celulares e notebooks
• os tokens de mensagem (tm_msg_) da caixa respondem 422 mailbox_login_suspended. Eles não são revogados, por isso voltam a funcionar quando o login é restaurado
• as senhas de dispositivo para sincronização de arquivos são revogadas, e essa revogação é permanente; novas senhas são criadas depois que a suspensão é removida
• os links de redefinição de senha e os códigos de recuperação deixam de funcionar, e não é possível emitir novos; redefinir a senha não restaura o acesso, pois não é a senha que o está bloqueando
• os e-mails recebidos são entregues normalmente, e as regras de encaminhamento e os filtros continuam funcionando

Nada é excluído. Todas as mensagens, contatos, eventos de calendário e arquivos permanecem onde estão, e a caixa continua contando para o seu plano e o armazenamento dele. Ela continua recebendo mensagens.

Migrações para uma caixa suspensa

Uma migração não pode ser iniciada para uma caixa suspensa: POST /api/v1/migrations responde 422 mailbox_login_suspended. O importador faz login para entregar as mensagens copiadas, portanto a tarefa falharia no meio do processo. Restaure o login, execute a migração e suspenda novamente se ainda for necessário.

Caixas de correio compartilhadas

As caixas compartilhadas são recusadas no endpoint individual com 422 mailbox_unavailable e ignoradas, mas ainda contabilizadas, pelo endpoint em massa. Ninguém entra diretamente em uma caixa compartilhada: sua equipe a abre a partir das próprias caixas. Portanto, suspender a caixa dessa pessoa é o que fecha a porta, inclusive na caixa compartilhada. Armazenar uma suspensão no registro compartilhado daria a impressão de fazer algo sem mudar nada.

Erros que você pode encontrar