Gmail Auto Cleaner

Un script Google Apps Script qui vide votre boîte mail en arrière-plan,
vague par vague, sans jamais supprimer vos favoris.

┌───────────────────────────────────────────────────────────────────┐
│  Mails > 30 jours  →  corbeille automatique  →  répété en boucle  │
│  ⭐ Favoris préservés · 🛡️ Anti-quota intégré · 🔁 Auto-reprise    │
└───────────────────────────────────────────────────────────────────┘

---

✨ Fonctionnalités

Fonctionnalité	Détail
🗑️ Nettoyage automatique	Supprime les mails de plus de 30 jours (configurable)
⭐ Favoris protégés	Les mails étoilés ne sont jamais touchés
🔁 Traitement par vagues	200 mails max par vague, puis reprise 1 min plus tard
🛡️ Anti-quota Gmail	Détecte les erreurs de quota et se met en pause 24h
🕓 Maintenance quotidienne	Tourne chaque nuit à 4h sans intervention manuelle
🧹 Zéro config	Un copier-coller, deux clics, et c'est parti

---

🧠 Comment ça marche

Google Apps Script impose des limites quotidiennes sur les appels à l'API Gmail. Ce script contourne ces limites en découpant le travail en petites vagues indépendantes.

[4h du matin]
     │
     ▼
maintenanceSweep()
     │
     ├─ Cherche les mails > 30j (sans étoile, hors corbeille/spam)
     ├─ Envoie jusqu'à 200 mails à la corbeille
     │
     ├─ [S'il reste des mails] ──► planifie continuationSweep() dans 1 min
     │        │
     │        └─ [répète jusqu'à épuisement ou quota atteint]
     │
     └─ [Quota atteint] ──► pause 24h ──► quotaResumeSweep() ──► reprend

---

🚀 Mise en place (5 minutes)

Étape 1 — Ouvrir Google Apps Script

Rendez-vous sur script.google.com et créez un nouveau projet.

Nommez-le comme vous voulez : Gmail Auto Cleaner, Inbox Cleanup, etc.

---

Étape 2 — Coller le script

1. Supprimez le contenu par défaut du fichier Code.gs
2. Copiez l'intégralité du fichier Code.gs de ce repo
3. Collez-le dans l'éditeur
4. Enregistrez avec Ctrl+S (ou ⌘+S sur Mac)

---

Étape 3 — Autoriser le script

La première exécution demande des permissions.
Le script accède uniquement à votre Gmail pour déplacer des mails à la corbeille.

⚠️ Google affichera un avertissement "application non vérifiée" car le script n'est pas publié sur le Store. Cliquez sur Paramètres avancés → Accéder au projet pour continuer.

---

Étape 4 — Installer le déclencheur quotidien

Dans l'éditeur, sélectionnez la fonction installMaintenanceTrigger dans le menu déroulant, puis cliquez sur ▶ Exécuter.

Résultat attendu dans les logs :
  Déclencheur de maintenance installé : tous les jours à 4h.

---

Étape 5 — Lancer le premier nettoyage immédiatement

Sélectionnez la fonction startFullCleanupNow, puis cliquez sur ▶ Exécuter.

Résultat attendu dans les logs :
  Vague terminée : 200 mails envoyés à la corbeille.
  Prochaine vague planifiée dans 1 minute.

Le script tourne maintenant seul. Chaque vague enchaîne la suivante automatiquement.

---

⚙️ Configuration

Tout se règle en haut du fichier Code.gs :

const DAYS_OLD = 30;               // ← mails plus vieux que X jours
const MAX_THREADS_PER_RUN = 40;   // ← nb de threads analysés par vague
const MAX_MESSAGES_PER_RUN = 200; // ← nb max de mails supprimés par vague
const API_BATCH_LIMIT = 100;      // ← taille des lots d'appel API (ne pas dépasser 100)
const QUOTA_PAUSE_HOURS = 24;     // ← durée de pause si quota Gmail atteint

Exemples de réglages courants

Objectif	DAYS_OLD	MAX_MESSAGES_PER_RUN
Nettoyage agressif (tout > 7j)	7	200
Nettoyage modéré (> 30j)	30	200
Nettoyage doux (> 90j)	90	100

---

📋 Référence des fonctions

Fonctions manuelles (à exécuter dans l'éditeur)

Fonction	Rôle
installMaintenanceTrigger()	Installe le déclencheur quotidien à 4h (à faire une fois)
startFullCleanupNow()	Lance un nettoyage immédiat complet
stopAllAutoCleanup()	Supprime tous les déclencheurs (arrêt complet)

Fonctions automatiques (ne pas exécuter manuellement)

Fonction	Rôle
maintenanceSweep()	Vague quotidienne (4h du matin)
continuationSweep()	Vague de continuation (auto, +1 min)
quotaResumeSweep()	Reprise après pause quota (auto, +24h)

---

🛡️ Gestion des quotas Gmail

Google impose une limite d'appels API Gmail par jour. Si le script la dépasse :

1. L'erreur est détectée automatiquement
2. Le script se met en pause pour 24h
3. Un déclencheur quotaResumeSweep est planifié
4. Le nettoyage reprend automatiquement après la pause

Aucune intervention manuelle nécessaire.

---

❓ FAQ

Q : Mes mails étoilés sont-ils en danger ?
Non. Le script vérifie !message.isStarred() avant chaque suppression. Les favoris sont intouchables.

Q : Les mails vont vraiment à la corbeille ou sont supprimés définitivement ?
Ils vont à la corbeille Gmail. Google les supprime définitivement après 30 jours supplémentaires. Vous avez donc le temps de récupérer une erreur.

Q : Le script peut-il tourner sur un compte Google Workspace ?
Oui, mais les quotas Gmail sont différents selon le plan Workspace. Le comportement anti-quota reste identique.

Q : Comment arrêter définitivement le script ?
Exécutez stopAllAutoCleanup() depuis l'éditeur. Tous les déclencheurs sont supprimés.

Q : Puis-je changer DAYS_OLD sans tout réinstaller ?
Oui. Modifiez la valeur, enregistrez, et le changement s'applique à la prochaine vague.

---

📁 Structure du repo

gmail-auto-cleaner/
├── Code.gs           ← Script principal (à coller dans Apps Script)
├── appsscript.json   ← Manifest (permissions OAuth, timezone)
└── README.md         ← Ce fichier

---

📄 Licence

MIT — libre d'utilisation, de modification et de distribution.

---

Fait avec ☕ et un peu trop d'emails non lus.