Mailbox API pour mailcow — installation et guide de l’API
Installation
- Le module est livré avec mailcow Toolkit 0.5.0 ou plus récent (un paquet, une licence par produit). Sur l’hôte mailcow, en root, lancez l’installateur du Toolkit comme d’habitude :
sudo ./install.sh --mailcow-dir /opt/mailcow-dockerized --name <instance>. Il copiedata/web/mlw-mailbox-api/, ajoute l’entrée de menu, la tâche de l’agent et le minuteur, puis recharge php-fpm. - Ouvrez System → Mailbox API dans l’administration mailcow. La page affiche la bannière de licence puis les réglages.
Licence
Dans System → Updates (Toolkit), carte Mailbox API for mailcow : collez la clé et activez-la, ou démarrez l’essai de 30 jours. En ligne de commande : php /web/mlw-toolkit/cli.php activate mailcow-mailbox-api <CLÉ> dans php-fpm-mailcow. La licence est vérifiée chaque jour ; sans internet le module fonctionne 7 jours après la dernière vérification réussie. Sans licence valide l’API répond 503 not_licensed, le minuteur n’envoie rien et rien n’est supprimé.
Réglages
- API activée : active ou coupe l’API.
- Adresse publique de l’API : base des liens signés des pièces jointes, par exemple
https://mail.example.com/mlw-mailbox-api/(vide = déduite de la page). - Messages par page (1–200) et pièce jointe maximale (1–100 Mo).
- Jeton du bot Telegram (de @BotFather), stocké chiffré ; un bot pour toutes les boîtes.
- Utilisateur master dovecot (facultatif), seulement si vous en avez défini un dans
mailcow.conf.
Clés API
Carte Clés API : nom, droits lire, envoyer, organiser, boîtes autorisées, puis Créer la clé. La clé (mbx_…) n’est affichée qu’une fois. Seul le SHA-256 est conservé ; Révoquer la désactive immédiatement. À chaque appel :
Authorization: Bearer mbx_…
Référence de l’API
Toutes les routes : https://<hôte mail>/mlw-mailbox-api/?r=<route> (le nginx de mailcow n’a pas de PATH_INFO). Réponses JSON ; toutes les routes sauf le lien signé exigent la clé avec le droit correspondant.
| Méthode et route | Droit | Fonction |
|---|---|---|
GET /v1/me |
quelconque | Nom, droits, boîtes, limites |
GET /v1/mailboxes |
quelconque | Boîtes autorisées, nombre de dossiers, UIDNEXT de INBOX |
GET /v1/folders&mailbox=… |
lire | Noms des dossiers |
GET /v1/messages&mailbox=…&folder=INBOX&limit=20&offset=0&q=…&unseen=1 |
lire | Liste des messages (les plus récents d’abord) |
GET /v1/messages/{uid}&mailbox=…&folder=… |
lire | Message complet : texte, HTML, en-têtes, pièces jointes (liens signés) |
POST /v1/messages/{uid}/read {"read":true} |
organiser | Lu/non lu |
POST /v1/messages/{uid}/move {"folder":"Archive"} |
organiser | Déplacer |
DELETE /v1/messages/{uid}… |
organiser | Supprimer |
POST /v1/send&mailbox=… {"to":"…","subject":"…","text":"…"} |
envoyer | Envoyer en tant que la boîte (cc, cci, html, reply_to) ; copie dans Envoyés |
GET /v1/attachments&…&t=… |
lien signé | Télécharger une pièce jointe |
Webhooks
Carte Boîtes surveillées : boîte, dossier (INBOX par défaut), adresse https de webhook et, en option, chat Telegram. Le module cherche chaque minute les nouveaux messages (UIDNEXT ; le premier passage ne fait que noter la position, l’ancien courrier n’est pas renvoyé). Chaque message produit un POST JSON avec event, mailbox, folder, uid, received_at et message (message_id, date, from, to, cc, subject, size, text, html, headers, attachments avec name, type, size, sha256 et url signée).
Vérifiez la signature :
X-MLW-Signature: t=1792300000,v1=<HMAC-SHA256(secret, "t.body")>
X-MLW-Event: message.received
Le secret est affiché à la création et par le bouton Secret. Les échecs sont réessayés après 30 s, 1 min, 2 min … jusqu’à cinq fois ; Dernières livraisons montre l’état et la réponse.
Telegram
Enregistrez le jeton du bot dans Réglages, puis mettez l’id du chat (utilisateur, groupe ou canal ; le bot doit en être membre) sur chaque boîte surveillée. Telegram à côté d’une boîte envoie un message de test avec l’expéditeur, le sujet et les 400 premiers caractères.
Dépannage
503 not_licensed: activez la licence (System → Updates (Toolkit)).502avec « no dovecot master credentials » :/etc/sogo/sieve.credsmanque ; vérifiez les conteneurs dovecot/sogo ou définissez l’utilisateur master à la main.403 not_allowed: la clé ne couvre pas la boîte ou n’a pas le droit.- Aucun webhook : surveillant actif ? adresse https et 2xx ? regardez Dernières livraisons ;
systemctl status mlw-mailcow-mailapi-<nom>.timer. - Pas d’ancien courrier après l’ajout : volontaire, le premier passage note seulement la position actuelle.