De ce ai nevoie de asta
mailcow vine cu un API de administrare. E foarte bun pentru crearea de domenii, cutii poștale și aliasuri, dar nu spune nimic despre mailul din interiorul unei cutii poștale. Dacă vrei ca un script, un CRM sau un flux de automatizare să citească o căsuță partajată, să trimită un răspuns ca acea adresă sau să mute un mesaj într-un folder, API-ul de administrare te lasă singur.
Mailbox API for mailcow umple acest gol. Le oferă programelor tale o interfață REST controlată către mailul propriu-zis: listează foldere și mesaje, caută, citește mesajul complet cu atașamente, trimite ca acea cutie poștală și marchează, mută sau șterge. În plus, fiecare cutie poștală monitorizată poate trimite fiecare mesaj nou către un webhook https ca JSON semnat și către un chat Telegram. Totul rulează în rețeaua ta mailcow, iar tu decizi ce cutii poștale și ce drepturi primește fiecare cheie.
Acest tutorial parcurge configurarea așa cum am făcut-o pe propriul meu host: mai întâi cheile, apoi citirea și trimiterea, apoi webhook-urile către un instrument de automatizare precum n8n și, la final, notificările Telegram.
Cerințe preliminare
- mailcow-dockerized pe Linux cu docker compose și systemd, plus mailcow Toolkit 0.5.0 sau mai nou de la MediaLab Works instalat (acest produs este unul dintre modulele sale, cu licență proprie).
- Acces root pe host pentru a rula instalatorul Toolkit și acces HTTPS de ieșire de pe server către
medialab.workspentru verificarea licenței. - O adresă https pentru API, folosită în linkurile semnate către atașamente și, pentru webhook-uri, un endpoint https al tău.
- Opțional: un token de bot Telegram de la @BotFather și chat id-ul fiecărei cutii poștale pe care vrei să o notifici.
- Modulul este open source (GPL-3.0), așa că primești codul sursă complet.
Pasul 1 — Instalează modulul și activează licența
Modulul vine în pachetul Toolkit. Pe hostul mailcow, ca root, rulează instalatorul ca de obicei:
sudo ./install.sh --mailcow-dir /opt/mailcow-dockerized --name <instance>
Acesta copiază data/web/mlw-mailbox-api/, adaugă elementul de meniu, jobul agentului de host și timerul care rulează o dată pe minut, apoi reîncarcă php-fpm. Deschide apoi System → Mailbox API în meniul de administrare mailcow; vei vedea un banner de licență și setările dedesubt.
Pentru activare, deschide System → Updates (Toolkit) și găsește cardul Mailbox API for mailcow: lipește cheia și activeaz-o, sau începe perioada de probă. În shell același lucru este posibil cu php /web/mlw-toolkit/cli.php activate mailcow-mailbox-api <KEY> în interiorul php-fpm-mailcow. Licența este verificată zilnic; fără internet, modulul continuă să funcționeze 7 zile după ultima verificare reușită. Fără o licență validă, API-ul răspunde 503 not_licensed și timerul nu trimite nimic, dar cutiile poștale și mesajele rămân neatinse.
Pasul 2 — Activează API-ul și setează elementele de bază
În System → Mailbox API:
- API on pornește sau oprește API-ul. Licența este verificată oricum.
- Public API address este adresa folosită în linkurile semnate către atașamente, de exemplu
https://mail.example.com/mlw-mailbox-api/. Lasă-l gol pentru a o deduce din pagină. - Messages per page (1–200) și largest attachment (1–100 MB) îți stabilesc limitele.
- Dovecot master user este opțional și necesar doar dacă îți setezi propriul utilizator în
mailcow.conf; implicit, modulul citește credențialele master pe care mailcow le creează la pornire. - Telegram bot token este opțional deocamdată; revenim la el la Pasul 6.
Pasul 3 — Creează chei cu drepturi limitate
În cardul API keys, dă cheii un nume, bifează drepturile de care are nevoie — read, send, organize — alege cutiile poștale pe care le poate folosi și apasă Create key. Cheia (mbx_…) este afișată o singură dată, la creare, așa că salveaz-o imediat. Lista arată prefixul, drepturile, cutiile poștale și ultima utilizare; Revoke o dezactivează imediat. În baza de date se păstrează doar SHA-256 al cheii, iar fiecare apel este jurnalizat.
Aceasta este partea care îmi place cel mai mult pentru automatizări: un flux care doar mută mailul primit în foldere primește o cheie cu organize pe o singură cutie poștală și nimic altceva. Un script de notificare primește doar read. Nu dai niciodată o cheie care poate ajunge la toate cutiile poștale de pe server.
Trimite cheia la fiecare apel:
Authorization: Bearer mbx_…
Pasul 4 — Citește și organizează mailul
Toate rutele se apelează pe https://<mail host>/mlw-mailbox-api/?r=<route> — nginx-ul din mailcow nu are PATH_INFO, așa că ruta stă în query string. Răspunsurile sunt JSON. Toate rutele, cu excepția linkului semnat către atașament, necesită cheia, iar cheia trebuie să permită cutia poștală și dreptul respectiv.
Începe prin a verifica ce poate face o cheie:
curl -H "Authorization: Bearer $KEY" \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/me"
GET /v1/me returnează numele cheii, drepturile, cutiile poștale și limitele; GET /v1/mailboxes listează cutiile poștale permise cu numărul de foldere și INBOX UIDNEXT. Pentru a vedea folderele și o pagină cu cele mai noi mesaje:
curl -H "Authorization: Bearer $KEY" \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/folders&mailbox=office@example.com"
curl -H "Authorization: Bearer $KEY" \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/messages&mailbox=office@example.com&folder=INBOX&limit=20&offset=0&unseen=1"
Lista de mesaje acceptă q= pentru căutare și unseen=1 pentru doar cele necitite și vine cu cele mai noi primele, cu uid, subiect, de la, către, dată, dimensiune și seen. Citirea unui mesaj returnează textul, HTML-ul, antetele și atașamentele (nume, tip, dimensiune, url semnat):
curl -H "Authorization: Bearer $KEY" \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/messages/1234&mailbox=office@example.com&folder=INBOX"
Atașamentele vin ca linkuri semnate care expiră după 1 oră și sunt legate de cheia API care poate citi cutia poștală, așa că le poți descărca fără să trimiți cheia mai departe. Regenerarea unui link înseamnă citirea din nou a mesajului prin API.
Cu dreptul organize poți marca citit sau necitit, muta și șterge:
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"read":true}' \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/messages/1234/read&mailbox=office@example.com&folder=INBOX"
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"folder":"Archive"}' \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/messages/1234/move&mailbox=office@example.com&folder=INBOX"
Un DELETE pe /v1/messages/{uid} șterge definitiv mesajul. Erorile sunt JSON cu un status HTTP: 401 cheie lipsă sau greșită, 403 cheia nu are drept pe acea cutie poștală, 404 rută sau mesaj necunoscut, 422 date de intrare invalide, 429/502 limite sau o eroare de server.
Pasul 5 — Trimite ca acea cutie poștală
Trimiterea necesită dreptul send. Corpul cererii ia to, subject și text și acceptă și cc, bcc, html și reply_to. O copie este pusă în Sent, ceea ce contează dacă cineva deschide mai târziu acea cutie poștală și se întreabă ce s-a răspuns:
curl -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"to":"customer@example.org","subject":"Your invoice","text":"Attached."}' \
"https://mail.example.com/mlw-mailbox-api/?r=/v1/send&mailbox=office@example.com"
Nimic nu pleacă spre medialab.works; mesajul iese prin propriul tău mailcow.
Pasul 6 — Webhook-uri pentru mail nou, verificate
În cardul Monitored mailboxes adaugă o cutie poștală, folderul de urmărit (implicit INBOX), o adresă de webhook https și, opțional, un chat id Telegram. Modulul verifică în fiecare minut dacă există mesaje noi, folosind UIDNEXT pe folder. Reține cum funcționează: prima rulare doar stabilește punctul de pornire, așa că nu se retrimite mail vechi — mailul nou de la acel moment înainte este livrat.
Fiecare mesaj nou produce un POST JSON cu event, mailbox, folder, uid, received_at și un obiect message care conține message_id, date, from, to, cc, subject, size, text, html, headers și attachments (name, type, size, sha256 și un url semnat).
Înainte să folosești corpul cererii, verifică antetul cu semnătura:
X-MLW-Signature: t=1792300000,v1=<hex HMAC-SHA256(secret, "t.body")>
X-MLW-Event: message.received
Fiecare monitor are propriul secret, generat la prima utilizare; pagina îl arată la crearea monitorului și cu butonul Secret. Compară HMAC-ul cu secretul tău și respinge timestamp-urile mai vechi de cinci minute. În n8n, de exemplu, pune această verificare într-un mic nod Code sau Function imediat după nodul Webhook, înainte ca orice altceva să atingă payload-ul.
Livrările eșuate sunt reîncercate după 30 s, 1 min, 2 min … până la cinci încercări. Livrările sunt puse în coadă în baza de date și trimise de timerul care rulează o dată pe minut, iar cardul Recent deliveries arată statusul și răspunsul — primul loc unde te uiți când un flux pare tăcut.
Pasul 7 — Notificări Telegram per cutie poștală
Lipește tokenul botului la Settings (este stocat criptat, se afișează doar ultimele patru caractere; un singur bot deservește toate cutiile poștale). Apoi pune chat id-ul — un utilizator, un grup sau un canal — pe fiecare cutie poștală monitorizată. Botul trebuie să fie membru și, pentru canale, administrator. Telegram de lângă o cutie poștală trimite un mesaj de test. Notificarea arată expeditorul, subiectul și primele 400 de caractere din text.
Se potrivește bine pentru o căsuță partajată: un chat per cutie poștală monitorizată și vezi mailul nou pe telefon fără să deschizi un client de mail.
Sfaturi și depanare
503 not_licensed: activează licența în System → Updates (Toolkit); fără internet, modulul funcționează 7 zile după ultima verificare.502 server_errorcu „no dovecot master credentials”: mailcow nu a creat/etc/sogo/sieve.creds; verifică faptul că dovecot-mailcow și sogo-mailcow rulează sau setează manual utilizatorul și parola master.403 not_allowed: cheia nu acoperă acea cutie poștală sau nu are dreptul necesar; creează o cheie nouă cu domeniul potrivit în pagina de administrare.- Nu ajunge niciun webhook: verifică faptul că monitorul este activ, că adresa este https și răspunde cu 2xx și uită-te la Recent deliveries; timerul rulează în fiecare minut (
systemctl status mlcow-mailapi-<name>.timer). - Nu apare mail vechi după adăugarea unui monitor: prin design, prima rulare doar înregistrează poziția curentă.
- Ține Public API address setat la adresa ta https reală; altfel linkurile semnate către atașamente indică spre locul greșit.
- API-ul nu creează, nu șterge și nu modifică cutii poștale; lucrează doar în cutiile poștale pe care le permiți. Citește poșta prin login-ul master al dovecot, în rețeaua mailcow — același mecanism pe care mailcow îl folosește pentru imapsync.
Concluzie
API-ul de administrare gestionează serverul; acest modul gestionează mailul, o cheie cu drepturi limitate pe rând. Cu o cheie read/send/organize per cutie poștală, webhook-uri semnate către n8n și un chat Telegram pentru căsuțele care te interesează, obții automatizare în jurul propriului mailcow fără să dai nimic la o parte. Începe cu o singură cutie poștală și o cheie doar pentru citire, confirmă că verificarea semnăturii webhook-ului funcționează, apoi extinde domeniul. Ghidul de utilizare are tabelul complet al rutelor, iar changelog-ul urmărește actualizările; dacă ceva nu se potrivește, baza de cunoștințe și FAQ sunt următoarele opriri bune, sau contactează-ne.