mail_checker/README.md

Mail Checker

Mail Checker je napredna i potpuno funkcionalna Python aplikacija koja radi unutar sistemske trake (System Tray) i služi za praćenje nepročitanih poruka s više IMAP računa istovremeno.

Aplikacija podržava:

• zvučne obavijesti
• glasovna upozorenja na hrvatskom jeziku (TTS)
• pregled i čitanje zadnjih poruka kroz tabove
• sigurno pohranjivanje lozinki

Napomena o kompatibilnosti:
Ova aplikacija razvijena je isključivo za Linux sustave te je službeno testirana i optimizirana na Debian 13 (Trixie) operativnom sustavu.

---

✨ Funkcionalnosti

• Praćenje više računa
  Sinkronizirana provjera više e-mail računa s različitim IMAP poslužiteljima.

• Fleksibilni intervali
  Svaki račun može imati vlastiti interval provjere (minimalno 10 sekundi).

• Napredne obavijesti

  • Desktop notifikacije preko sistemskog daemon-a (notify-send)

  • Prilagođene zvučne datoteke (.wav, .mp3) za svaki račun zasebno

  • Glasovni alert (TTS): Izgovaranje broja nepročitanih poruka na hrvatskom jeziku uz ispravnu gramatičku deklinaciju:

    • 1 poruku
    • 2 poruke
    • 5 poruka

    Podržan je izbor muškog ili ženskog glasa.

• Pregled poruka
  Sučelje s tabovima unutar kojeg možete pročitati tekstualni sadržaj zadnjih poruka ili ih trajno obrisati (prebaciti u Trash).

• Visoka sigurnost
  Integracija sa sistemskim privjeskom ključeva (keyring) – lozinke se ne zapisuju u plain-text obliku unutar konfiguracijske datoteke ako je privjesak dostupan.

• Otpornost na mrežne greške
  Implementiran je exponential backoff mehanizam za ponovne pokušaje u slučaju gubitka mrežne veze.

---

🛠️ Potpuni zahtjevi i instalacija (Debian 13)

Kako bi aplikacija radila bez pogrešaka i upozorenja u terminalu, potrebno je instalirati sve sistemske biblioteke i Python pakete.

1. Instalacija sistemskih paketa (APT)

Otvorite terminal i pokrenite sljedeću naredbu:

sudo apt update

sudo apt install python3-tk python3-pil python3-pystray python3-keyring \
                 espeak-ng mpv \
                 libayatana-appindicator3-1 \
                 libayatana-appindicator-glib1 \
                 libnotify-bin \
                 gir1.2-gtop-2.0 \
                 dbus-x11

Pojašnjenje paketa

• python3-tk
  Omogućuje rad Tkinter grafičkog sučelja u Pythonu.

• python3-pil
  Pillow biblioteka za generiranje i manipulaciju ikona u sistemskoj traci.

• python3-pystray
  Omogućuje kreiranje i upravljanje ikonom u sistemskoj traci.

• python3-keyring
  Omogućuje Pythonu komunikaciju sa sustavnim privjeskom ključeva za sigurno spremanje lozinki.

• espeak-ng
  TTS pokretač koji generira glasovne obavijesti na hrvatskom jeziku.

• mpv
  Media player koji aplikacija koristi za reprodukciju .mp3 i .wav datoteka bez blokiranja sučelja.

• libayatana-appindicator3-1

• libayatana-appindicator-glib1

  Sustavne biblioteke ključne za ispravan prikaz ikone u sistemskoj traci (AppIndicator).

• libnotify-bin
  Omogućuje slanje desktop obavijesti putem naredbe notify-send.

• dbus-x11
  Osigurava stabilnu komunikaciju aplikacije sa sistemskim servisima.

---

🚀 Pokretanje aplikacije

Aplikaciju pokrećete iz njezinog direktorija standardnom naredbom:

python3 mail_checker.py

---

⚙️ Korisničko sučelje (Postavke i pregled)

Upravljanje računima

Prozor za postavke podijeljen je na dva dijela:

Lijeva strana

• Popis registriranih računa
• Horizontalni klizač za dugačke adrese
• Gumbi ▲ / ▼ za promjenu redoslijeda provjere

Desna strana

Formular za unos detalja računa:

• Nadimak
• IMAP server
• Email
• Lozinka
• Interval provjere
• Zvučna datoteka
• TTS postavke
• Opcije pregleda

---

Pregled poruka

Klikom na Pregled poruka unutar izbornika sistemske trake otvara se prozor koji dohvaća najnovije poruke za sve račune koji imaju uključenu opciju prikaza.

Dvostrukim klikom na poruku otvara se prozor za čitanje tekstualnog sadržaja s opcijom izravnog brisanja poruke sa servera.

---

📁 Struktura datoteka

Aplikacija koristi i stvara sljedeće datoteke:

• mail_checker.py
  Glavni izvorni kod aplikacije.

• config.json
  Konfiguracijska datoteka u kojoj se čuvaju postavke računa.

• mail_checker.log
  Detaljan dnevnik rada i pogrešaka (log file).

---

🔒 Sigurnost lozinki (Keyring Helper)

Aplikacija automatski prepoznaje podržava li vaše radno okruženje privjesak ključeva (GNOME Keyring ili KDE Wallet).

• Ako je privjesak dostupan

  • Polje "MAIL_PASSWORD" unutar config.json ostat će prazno ("")
  • Lozinka će biti sigurno pohranjena pod servisom MailChecker

• Ako privjesak nije dostupan

  • Aplikacija zapisuje upozorenje u log
  • Lozinka se sprema lokalno u config.json kako bi aplikacija mogla nastaviti raditi

---

🐛 Rješavanje problema i dnevnik rada (Logging)

Sve akcije, promjene stanja, uspješni dohvat poruka te IMAP ili mrežne pogreške zapisuju se u datoteku:

mail_checker.log

Praćenje loga u stvarnom vremenu:

tail -f mail_checker.log