Suspender el inicio de sesión por API

Suspender el inicio de sesión impide que una persona entre en un buzón mientras el buzón sigue funcionando. El correo se entrega con normalidad y espera allí; nada rebota ni se pierde. Esta página es la referencia de comandos para configurar esta opción.

El mismo control está en el panel, en Buzones → (un buzón) → Límites. Está disponible en todos los planes y no tiene coste adicional.

Suspender o pausar: no son la misma llamada

Usa :suspend-login para un cliente que no ha pagado, una persona entre contratos o cualquiera cuyo correo todavía quieras recibir. Usa :pause cuando el buzón deba detenerse por completo, incluidos los remitentes.

Existe un tercer estado al que no llega ninguna de las dos llamadas. Si la actividad saliente indica que se ha usado indebidamente la contraseña de un buzón, TrekMail puede impedir que ese buzón envíe y mantener activos el inicio de sesión y la entrega. Los envíos devuelven entonces 403 mailbox_sending_paused. Ni :resume ni :resume-login lo eliminan, y repetir la llamada tampoco: hay que cambiar la contraseña y soporte vuelve a activar el envío. Consulta ¿Por qué no puedo enviar correos?.

Permiso necesario

mailboxes:write, el mismo permiso que actualiza cualquier otro campo del buzón. Todos los endpoints siguientes aceptan una cabecera Idempotency-Key.

Un buzón

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 es opcional y admite hasta 255 caracteres. Se muestra en tu panel y la API lo devuelve; el usuario suspendido nunca lo ve.

Para levantar la suspensión:

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 el estado

Tanto GET /api/v1/mailboxes/{id} como el endpoint de listado incluyen el estado, por lo que puedes auditarlo sin cambiar 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", "...": "..." } }

Ten en cuenta que status sigue siendo active. No es un error que debas sortear: el buzón está activo y recibe correo. Consulta login_suspended para el inicio de sesión y status para saber si el propio buzón está funcionando.

Varios buzones a la 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"}'

Proporciona exactamente un selector:

La respuesta te indica qué ha ocurrido:

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

matched indica cuántos buzones encontró el selector, updated cuántos cambiaron realmente y skipped a cuántos no se pudo aplicar la llamada. Los buzones que ya están en el estado solicitado coinciden, pero no se actualizan, así que es seguro repetir la llamada, algo útil si una tarea de facturación la ejecuta cada noche.

Establece "login_suspended": false para restaurar el mismo conjunto.

Con un 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")

Las tres herramientas están disponibles para un agente con el permiso necesario. En un servidor MCP alojado localmente, su administrador puede exigir aprobación explícita para las acciones de escritura, lo que evita que un agente bloquee usuarios por accidente.

Qué hace un buzón suspendido

La suspensión se aplica en todos los puntos de acceso, no se oculta en la interfaz:

• se rechaza el inicio de sesión en el correo web y se cierra cualquier sesión que ya estuviera abierta
• se rechaza la autenticación IMAP, POP y SMTP, por lo que las aplicaciones de correo dejan de funcionar y no se puede enviar nada
• se rechazan CalDAV y CardDAV, por lo que el calendario y los contactos dejan de sincronizarse con teléfonos y portátiles
• los tokens de mensajes (tm_msg_) del buzón responden 422 mailbox_login_suspended. No se revocan, por lo que vuelven a funcionar cuando se restaura el inicio de sesión
• las contraseñas de dispositivos para sincronizar archivos se revocan de forma permanente; se crean otras nuevas después de levantar la suspensión
• los enlaces para restablecer la contraseña y los códigos de recuperación dejan de funcionar, y no se pueden emitir otros nuevos; restablecer la contraseña no recupera el acceso porque no es la contraseña lo que lo bloquea
• el correo entrante se entrega con normalidad, y las reglas de reenvío y los filtros siguen funcionando

No se elimina nada. Cada mensaje, contacto, evento del calendario y archivo permanece en su sitio, y el buzón sigue contando para tu plan y su almacenamiento. Continúa recibiendo correo.

Migraciones a un buzón suspendido

No se puede iniciar una migración a un buzón suspendido: POST /api/v1/migrations responde 422 mailbox_login_suspended. El importador inicia sesión para entregar el correo que copia, por lo que la tarea fallaría a mitad del proceso. Restaura el inicio de sesión, ejecuta la migración y vuelve a suspenderlo si todavía lo necesitas.

Buzones compartidos

El endpoint individual rechaza los buzones compartidos con 422 mailbox_unavailable, mientras que el endpoint masivo los omite, aunque los sigue contabilizando. Nadie inicia sesión directamente en un buzón compartido: tu equipo lo abre desde su propio buzón, así que suspender el buzón de esa persona es lo que cierra el acceso, también en el buzón compartido. Guardar una suspensión en el registro compartido parecería hacer algo, pero no cambiaría nada.

Errores que puedes encontrar