Mailbox API für mailcow — Installation und API-Anleitung
Installation
- Das Modul steckt in mailcow Toolkit 0.5.0 oder neuer (ein Paket, eine Lizenz pro Produkt). Auf dem mailcow-Host als root den Toolkit-Installer wie gewohnt ausführen:
sudo ./install.sh --mailcow-dir /opt/mailcow-dockerized --name <Instanz>. Er kopiertdata/web/mlw-mailbox-api/, ergänzt den Menüeintrag, den Agent-Job und den Minutentimer und lädt php-fpm neu. - Öffne System → Mailbox API im mailcow-Admin. Die Seite zeigt den Lizenzbalken und darunter die Einstellungen.
Lizenz
Unter System → Updates (Toolkit) die Karte Mailbox API for mailcow öffnen: Schlüssel einfügen und aktivieren oder die 30-Tage-Testphase starten. Auf der Shell: php /web/mlw-toolkit/cli.php activate mailcow-mailbox-api <KEY> in php-fpm-mailcow. Die Lizenz wird täglich geprüft; ohne Internet läuft das Modul 7 Tage nach der letzten erfolgreichen Prüfung. Ohne gültige Lizenz antwortet die API mit 503 not_licensed, der Timer sendet nichts, nichts wird gelöscht.
Einstellungen
- API ein: API ein- oder ausschalten.
- Öffentliche API-Adresse: Basis für signierte Anhangslinks, z. B.
https://mail.example.com/mlw-mailbox-api/(leer = aus der Seite). - Nachrichten pro Seite (1–200) und größter Anhang (1–100 MB).
- Telegram-Bot-Token (von @BotFather), verschlüsselt gespeichert; ein Bot für alle Postfächer.
- Dovecot-Master-Benutzer (optional), nur wenn du selbst einen in
mailcow.confgesetzt hast.
API-Schlüssel
Karte API-Schlüssel: Namen geben, Rechte lesen, senden, organisieren ankreuzen, Postfächer wählen, Schlüssel erstellen. Der Schlüssel (mbx_…) wird einmal angezeigt. In der Datenbank steht nur der SHA-256; Widerrufen deaktiviert ihn sofort. Bei jedem Aufruf:
Authorization: Bearer mbx_…
API-Referenz
Alle Routen: https://<Mail-Host>/mlw-mailbox-api/?r=<Route> (mailcows nginx hat kein PATH_INFO). Antworten sind JSON; jede Route außer dem signierten Anhangsdownload braucht den Schlüssel mit dem passenden Recht.
| Methode und Route | Recht | Funktion |
|---|---|---|
GET /v1/me |
beliebig | Name, Rechte, Postfächer, Grenzen |
GET /v1/mailboxes |
beliebig | Erlaubte Postfächer, Ordnerzahl, INBOX-UIDNEXT |
GET /v1/folders&mailbox=… |
lesen | Ordnernamen |
GET /v1/messages&mailbox=…&folder=INBOX&limit=20&offset=0&q=…&unseen=1 |
lesen | Nachrichtenliste (neueste zuerst) |
GET /v1/messages/{uid}&mailbox=…&folder=… |
lesen | Vollständige Nachricht mit Text, HTML, Kopfzeilen, Anhängen (signierte Links) |
POST /v1/messages/{uid}/read {"read":true} |
organisieren | Gelesen/ungelesen |
POST /v1/messages/{uid}/move {"folder":"Archive"} |
organisieren | In anderen Ordner verschieben |
DELETE /v1/messages/{uid}… |
organisieren | Löschen |
POST /v1/send&mailbox=… {"to":"…","subject":"…","text":"…"} |
senden | Als das Postfach senden (cc, bcc, html, reply_to); Kopie nach Gesendet |
GET /v1/attachments&…&t=… |
signierter Link | Anhang herunterladen |
Webhooks
Karte Beobachtete Postfächer: Postfach, Ordner (Standard INBOX), https-Webhook-Adresse und optional Telegram-Chat. Jede Minute werden neue Nachrichten gesucht (UIDNEXT; der erste Lauf setzt nur den Startpunkt, alte Mail wird nicht nachgesendet). Jede neue Nachricht erzeugt ein JSON-POST mit event, mailbox, folder, uid, received_at und message (message_id, date, from, to, cc, subject, size, text, html, headers, attachments mit name, type, size, sha256 und signierter url).
Signatur prüfen:
X-MLW-Signature: t=1792300000,v1=<HMAC-SHA256(secret, "t.body")>
X-MLW-Event: message.received
Das Geheimnis zeigt die Seite beim Anlegen und über den Knopf Secret. Fehlversuche werden nach 30 s, 1 min, 2 min … bis fünf Versuche wiederholt; Letzte Zustellungen zeigt Status und Antwort.
Telegram
Bot-Token unter Einstellungen speichern, dann je Postfach die Chat-ID eintragen (Benutzer, Gruppe oder Kanal; der Bot muss Mitglied sein). Telegram neben dem Postfach sendet eine Testnachricht mit Absender, Betreff und den ersten 400 Zeichen.
Wenn etwas nicht geht
503 not_licensed: Lizenz aktivieren (System → Updates (Toolkit)).502mit „no dovecot master credentials”:/etc/sogo/sieve.credsfehlt; dovecot-/sogo-Container prüfen oder Master-Benutzer von Hand setzen.403 not_allowed: Schlüssel deckt das Postfach nicht oder hat das Recht nicht.- Kein Webhook: Monitor aktiv? Adresse https und 2xx? Letzte Zustellungen prüfen;
systemctl status mlw-mailcow-mailapi-<name>.timer. - Keine alte Mail nach dem Anlegen: absichtlich, der erste Lauf merkt sich nur die aktuelle Position.