Lokalny Cleaner Gmail bez wysyłania korespondencji na serwery zewnętrzne

W pewnym momencie każdy z nas otwiera swoją skrzynkę mailową i widzi dziesiątki tysięcy nieprzeczytanych wiadomości. Zniżki ze sklepów, w których kupowaliśmy coś pięć lat temu, podsumowania serwisów, powiadomienia z trackerów zadań. Ręczne czyszczenie w interfejsie Gmaila staje się koszmarem, ponieważ webowy klient Google niechętnie obsługuje zaznaczenia większe niż 50–100 wiadomości na raz.

Większość komercyjnych narzędzi do czyszczenia maili działa w modelu subskrypcyjnym. Żądają pełnego dostępu do konta i wysyłają Twoje wiadomości na własne serwery w celu analizy. Autor projektu gmail-cleaner podszedł do sprawy inaczej: stworzył lekkie narzędzie lokalne z interfejsem webowym, które działa wyłącznie na Twoim komputerze poprzez oficjalne API Gmaila.

Dlaczego warto przeprowadzać czyszczenie lokalnie

Główna idea projektu to pełna prywatność. Brak backendów zewnętrznych, zewnętrznych baz danych i płatnych planów. Cały stos działa lokalnie, a Twoje dane nigdzie nie trafiają.

Aplikacja rozwiązuje cztery powszechne problemy:

• Znajduje newslettery i pomaga zrezygnować z nich jednym kliknięciem.
• Grupuje wiadomości według nadawcy, pokazując, kto najbardziej zaśmieca Twoją skrzynkę.
• Masowo usuwa lub archiwizuje wątki od wybranych nadawców.
• Oznacza tysiące wiadomości jako przeczytane w ciągu kilku sekund.

Wszystkie usunięte wiadomości trafiają do standardowego kosza Gmaila. Jeśli przypadkowo usuniesz coś potrzebnego, masz 30 dni na odzyskanie danych przez standardowy interfejs webowy Google.

Aby przyspieszyć proces, narzędzie wykorzystuje wsadowe żądania API Gmaila, grupując do 100 operacji w jednym wywołaniu. Dlatego czyszczenie kilku tysięcy wiadomości zajmuje minimalny czas.

Co jest w środku i jak to działa

Pod maską znajdziesz Pythona 3.9+ oraz serwer WWW, który udostępnia przejrzysty interfejs w stylu samego Gmaila.

Z perspektywy bezpieczeństwa tworzysz własną aplikację w Google Cloud Console. Oznacza to, że tokeny OAuth należą wyłącznie do Ciebie, a uprawnienia są żądane tylko dla tego, co minimalnie niezbędne: dostęp do odczytu i modyfikacji wiadomości, aby przenosić je do kosza i zmieniać status przeczytania.

Pliki credentials.json i token.json są przechowywane lokalnie. W buildzie Dockera osobny wolumin ./data jest przewidziany do tego celu, więc nie będziesz musiał ponownie autoryzować się po restarcie kontenera.

Jak wdrożyć projekt

Najłatwiejszy sposób na uruchomienie projektu to Docker. Dla entuzjastów wirtualnych środowisk dostępna jest również opcja z użyciem menedżera pakietów uv.

Najpierw musisz przejść do Google Cloud Console, utworzyć projekt, włączyć API Gmaila i wygenerować identyfikator klienta OAuth (typ Aplikacja webowa dla Dockera lub Aplikacja desktopowa do bezpośredniego uruchomienia Pythona). Upewnij się, że dodałeś swój adres e-mail do listy użytkowników testowych na ekranie zgody OAuth.

Zapisz pobrany plik jako credentials.json w głównym katalogu projektu.

Uruchomienie przez Docker

Sklonuj repozytorium:

git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleaner

Umieść plik credentials.json obok niego i uruchom kontener:

docker compose pull && docker compose up

Następnie otwórz http://localhost:8766 w przeglądarce, kliknij przycisk Zaloguj się, pobierz link autoryzacji Google z logów kontenera i potwierdź dostęp.

Uruchomienie przez Pythona i uv

Jeśli nie chcesz konfigurować Dockera, możesz uruchomić skrypt bezpośrednio przez uv:

uv sync
uv run python main.py

Interfejs będzie dostępny pod tym samym adresem http://localhost:8766.

Filtry i eksport danych

Poza prostym czyszczeniem projekt zawiera zaawansowane filtry. Możesz sortować wiadomości według rozmiaru załączników, zakresu dat lub standardowych kategorii Gmaila (Promocje, Społeczności, Aktualizacje, Fora, Główne).

Jeśli chcesz zachować informacje o nadawcach i datach przed usunięciem starej korespondencji służbowej, interfejs może wyeksportować metadane do CSV.

Dla kogo to będzie przydatne

Projekt jest idealny dla każdego, czyja skrzynka przekroczyła 50 000 wiadomości i zbliża się do limitu darmowego miejsca w Google Drive.

Tak, początkowa konfiguracja wymaga 5–10 minut pracy z Google Cloud Console i utworzenia kluczy OAuth. Ale w zamian otrzymujesz narzędzie, które nie odczytuje Twoich wiadomości na serwerach zewnętrznych i nie wymaga miesięcznej subskrypcji dla podstawowej funkcjonalności czyszczenia.