Mailbox API para mailcow — instalación y guía de la API
Instalación
- El módulo viene con mailcow Toolkit 0.5.0 o más reciente (un paquete, una licencia por producto). En el host de mailcow, como root, ejecuta el instalador del Toolkit como siempre:
sudo ./install.sh --mailcow-dir /opt/mailcow-dockerized --name <instancia>. Copiadata/web/mlw-mailbox-api/, añade la entrada de menú, la tarea del agente y el temporizador por minuto, y recarga php-fpm. - Abre System → Mailbox API en la administración de mailcow. La página muestra la franja de licencia y, debajo, los ajustes.
Licencia
En System → Updates (Toolkit), tarjeta Mailbox API for mailcow: pega la clave y actívala, o empieza la prueba de 30 días. Por consola: php /web/mlw-toolkit/cli.php activate mailcow-mailbox-api <CLAVE> dentro de php-fpm-mailcow. La licencia se comprueba a diario; sin internet el módulo funciona 7 días desde la última comprobación correcta. Sin licencia válida la API responde 503 not_licensed, el temporizador no envía nada y no se borra nada.
Ajustes
- API activada: enciende o apaga la API.
- Dirección pública de la API: base de los enlaces firmados de adjuntos, por ejemplo
https://mail.example.com/mlw-mailbox-api/(vacío = se deduce de la página). - Mensajes por página (1–200) y adjunto máximo (1–100 MB).
- Token del bot de Telegram (de @BotFather), guardado cifrado; un bot para todos los buzones.
- Usuario master de dovecot (opcional), solo si has definido uno en
mailcow.conf.
Claves API
Tarjeta Claves API: nombre, derechos leer, enviar, organizar, buzones permitidos y Crear clave. La clave (mbx_…) se muestra una vez. Solo se guarda el SHA-256; Revocar la desactiva al instante. En cada llamada:
Authorization: Bearer mbx_…
Referencia de la API
Todas las rutas: https://<host de correo>/mlw-mailbox-api/?r=<ruta> (el nginx de mailcow no tiene PATH_INFO). Respuestas JSON; todas las rutas salvo el enlace firmado exigen la clave con el derecho correspondiente.
| Método y ruta | Derecho | Función |
|---|---|---|
GET /v1/me |
cualquiera | Nombre, derechos, buzones, límites |
GET /v1/mailboxes |
cualquiera | Buzones permitidos, nº de carpetas, UIDNEXT de INBOX |
GET /v1/folders&mailbox=… |
leer | Nombres de carpetas |
GET /v1/messages&mailbox=…&folder=INBOX&limit=20&offset=0&q=…&unseen=1 |
leer | Lista de mensajes (los más recientes primero) |
GET /v1/messages/{uid}&mailbox=…&folder=… |
leer | Mensaje completo: texto, HTML, cabeceras, adjuntos (enlaces firmados) |
POST /v1/messages/{uid}/read {"read":true} |
organizar | Leído/no leído |
POST /v1/messages/{uid}/move {"folder":"Archive"} |
organizar | Mover |
DELETE /v1/messages/{uid}… |
organizar | Borrar |
POST /v1/send&mailbox=… {"to":"…","subject":"…","text":"…"} |
enviar | Enviar como el buzón (cc, cco, html, reply_to); copia en Enviados |
GET /v1/attachments&…&t=… |
enlace firmado | Descargar un adjunto |
Webhooks
Tarjeta Buzones vigilados: buzón, carpeta (INBOX por defecto), dirección https del webhook y, opcionalmente, chat de Telegram. Cada minuto busca mensajes nuevos (UIDNEXT; la primera pasada solo fija el punto de partida, no reenvía correo antiguo). Cada mensaje genera un POST JSON con event, mailbox, folder, uid, received_at y message (message_id, date, from, to, cc, subject, size, text, html, headers, attachments con name, type, size, sha256 y url firmada).
Verifica la firma:
X-MLW-Signature: t=1792300000,v1=<HMAC-SHA256(secret, "t.body")>
X-MLW-Event: message.received
El secreto se muestra al crear el monitor y con el botón Secret. Los fallos se reintentan a los 30 s, 1 min, 2 min… hasta cinco veces; Últimas entregas muestra el estado y la respuesta.
Telegram
Guarda el token del bot en Ajustes y pon el id del chat (usuario, grupo o canal; el bot debe ser miembro) en cada buzón vigilado. Telegram junto al buzón envía un mensaje de prueba con remitente, asunto y los primeros 400 caracteres.
Si algo no funciona
503 not_licensed: activa la licencia (System → Updates (Toolkit)).502con «no dovecot master credentials»: falta/etc/sogo/sieve.creds; comprueba los contenedores dovecot/sogo o define el usuario master a mano.403 not_allowed: la clave no cubre el buzón o no tiene el derecho.- No llega ningún webhook: ¿monitor activo? ¿dirección https y 2xx? mira Últimas entregas;
systemctl status mlw-mailcow-mailapi-<nombre>.timer. - No llega el correo antiguo al añadir un monitor: intencionado, la primera pasada solo anota la posición actual.