📬 Gmail → Google Sheets Kategorizasyon Botu

Gelen kutunuzdaki mailleri otomatik olarak okuyup kategorize eden (İş, Pazarlama, Sosyal Medya, Şüpheli/Phishing vb.) ve sonuçları bir Google Sheet'e satır olarak ekleyen, tamamen otonom bir otomasyon.

• 🕐 Her 5 dakikada bir arka planda otomatik çalışır (launchd / cron / Task Scheduler)
• 🔴 Şüpheli/phishing belirtisi taşıyan mailleri sheet'te kırmızı renkle işaretler
• 🔒 Şifre/OTP/kart numarası gibi hassas verileri asla sheet'e kopyalamaz
• 📅 Yeni mailler eklendikçe sheet otomatik olarak tarihe göre sıralı kalır
• 🔄 Artımlı senkronizasyon — her çalıştırmada sadece yeni mailler işlenir, hiçbir şey tekrarlanmaz

---

Örnek Görünüm

---

Nasıl çalışır?

[Gmail]  --(Gmail API)-->  [Python betiği]  --(Sheets API)-->  [Google Sheet]
                                  ^
                                  |
                      [launchd: her 5 dakikada bir tetikler]

1. Betik, state.json dosyasındaki son çalışma zamanından sonra gelen mailleri Gmail API üzerinden çeker (artımlı/incremental senkronizasyon).
2. Her maili anahtar kelime tabanlı kurallarla kategorize eder ve şüpheli/phishing göstergelerine (aciliyet dili, domain uyuşmazlığı, tehlikeli ek, kısaltılmış link vb.) karşı kontrol eder.
3. Sonuçları Google Sheets API ile sheet'e ekler, şüpheli satırları koşullu biçimlendirme ile kırmızı işaretler, veriyi tarihe göre yeniden sıralar.

---

Kurulum (Python + zamanlayıcı)

0) Gereksinimler

• Python 3.9 veya üstü kurulu olmalı. Kontrol et:

  python3 --version

  Yoksa: macOS'ta brew install python, Windows'ta python.org'dan indir (kurulumda "Add Python to PATH" kutusunu işaretlemeyi unutma), Linux'ta genelde zaten kurulu gelir (sudo apt install python3 python3-venv gerekebilir).
• Bir Google hesabı (kişisel Gmail).

1) Google Cloud'da API erişimi oluştur

1. console.cloud.google.com → yeni proje oluştur
2. APIs & Services → Library → Gmail API ve Google Sheets API'yi ayrı ayrı Enable et
3. APIs & Services → Google Auth Platform → Audience:
   • User type: External
   • Test users kısmına kendi Gmail adresini ekle
4. APIs & Services → Google Auth Platform → Clients → Create Client:
   • Application type: Desktop app
   • credentials.json'ı indir, proje klasörüne koy

⚠️ Önemli: Proje "Testing" modunda kaldığı sürece Google, verilen izni 7 gün sonra otomatik geçersiz kılar. Bot durursa (invalid_grant hatası), token.json'ı silip betiği bir kez daha elle çalıştırman yeterli — bkz. Sorun Giderme.

2) Kendi Google Sheet'ini oluştur

Boş bir Google Sheet oluştur, URL'sindeki uzun ID'yi kopyala:

https://docs.google.com/spreadsheets/d/BU_KISIM_SHEET_ID/edit

3) Config dosyanı hazırla

cp config.example.json config.json

config.json içindeki spreadsheet_id alanına kendi Sheet ID'ni yaz.

4) Python ortamını kur

macOS / Linux:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Windows (PowerShell):

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

5) İlk çalıştırma (izin vermek için)

python gmail_kategori_bot.py

Tarayıcı açılır, Google hesabınla giriş yapıp izin verirsin. Bu, token.json dosyasını oluşturur — bundan sonra tarayıcı açılmadan sessizce çalışır.

⚠️ İlk çalıştırmada Google "Bu uygulama doğrulanmadı" uyarısı gösterebilir (normal — bu kişisel/tek kullanıcılı bir proje). "Gelişmiş" (Advanced) → "[proje adı]'a git (güvenli değil)" diyerek devam et.

6) Otomatik zamanlama

macOS (launchd):

cp com.example.gmailkategoribot.plist.template ~/Library/LaunchAgents/com.example.gmailkategoribot.plist

Kopyaladığın dosyadaki /path/to/gmail_bot yollarını kendi gerçek klasör yoluna göre düzenle (pwd komutuyla öğrenebilirsin), sonra:

launchctl load ~/Library/LaunchAgents/com.example.gmailkategoribot.plist

Kontrol için:

launchctl list | grep gmailkategoribot
cat gmail_bot.log

Windows (Task Scheduler):

1. Başlat → "Görev Zamanlayıcı" (Task Scheduler) → Temel Görev Oluştur
2. Tetikleyici: Daily, saat: istediğin saat
3. Eylem: Start a program → Program: venv\Scripts\python.exe'in tam yolu (where python ile venv aktifken bulabilirsin) → Argümanlar: gmail_kategori_bot.py'ın tam yolu → "Start in": proje klasörü
4. Daha sık çalıştırmak istersen (örn. 5 dakikada bir), oluşturduğun görevi aç → Triggers → Edit → "Repeat task every" kutusunu işaretleyip 5 dakika seç

Linux (cron):

crontab -e

şu satırı ekle (yolları kendine göre düzenle):

*/5 * * * * /path/to/gmail_bot/venv/bin/python3 /path/to/gmail_bot/gmail_kategori_bot.py >> /path/to/gmail_bot/cron.log 2>&1

---

Kategori kuralları

Kategori	Belirleme kriteri
İş	Toplantı/proje/rapor içeren mailler
Finans/Fatura	Fatura, ödeme, ekstre içeren mailler
Alışveriş/Kargo	Sipariş onayı, kargo takip
Sosyal Medya	LinkedIn, Pinterest, Instagram vb. platform bildirimleri
Bildirim/Otomatik	no-reply gönderenler, güvenlik/doğrulama bildirimleri
Pazarlama/Reklam	İndirim, kampanya, bülten
Abonelik/Üyelik	Üyelik yenileme hatırlatmaları
Şüpheli/Phishing Adayı	Domain uyuşmazlığı + aciliyet dili/kimlik bilgisi talebi
Diğer/Kontrol Edilmeli	Yukarıdakilerden hiçbirine uymayan

Kuralları gmail_kategori_bot.py dosyasının başındaki anahtar kelime listelerinden (FINANCE_KEYWORDS, MARKETING_KEYWORDS vb.) özelleştirebilirsin.

---

Sorun Giderme

Hata	Sebep	Çözüm
403 access_denied	Google hesabın test users listesine eklenmemiş	Google Auth Platform → Audience → Test users
invalid_grant / token expired	Testing modunda 7 gün sınırı doldu	rm token.json sonra betiği tekrar çalıştır
Unable to find the server at ...googleapis.com	Geçici internet/DNS sorunu	Bağlantıyı kontrol et, tekrar dene
Unable to parse range	Sheet sekme adı yanlış	Kod artık sekme adını otomatik buluyor, sorun olmamalı
externally-managed-environment (pip)	macOS sistem Python'u korumalı	venv kullan (yukarıdaki adım 4)

---

Güvenlik notları

• Bot hiçbir maili silmez, arşivlemez, yanıtlamaz — sadece okur.
• Şifre/OTP/kart numarası gibi veriler sheet'e asla ham haliyle yazılmaz, [GİZLENDİ] ile maskelenir.
• Gmail için sadece okuma (readonly) izni istenir, yazma/silme izni istenmez.
• credentials.json, token.json, config.json dosyaları .gitignore ile hariç tutulmuştur — bunları asla paylaşmayın veya commit etmeyin.

---

Lisans

MIT