---
title: Gmail Cleaner
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, email, gmail, nettoyage, nodejs]
confidence: high
contested: false
sources: [https://selfh.st/apps/?tag=Email, https://github.com/TrshKnn/GmailCleaner]
---

# 📧 Gmail Cleaner

> **Outil spécialisé de nettoyage Gmail** : suppression en masse, archivage et filtrage automatisé directement via l'API Gmail — idéal pour reprendre le contrôle d'une boîte saturée.

## 📋 Informations Générales

| Champ | Valeur |
| :--- | :--- |
| **Site web** | N/A (projet GitHub) |
| **GitHub** | [TrshKnn/GmailCleaner](https://github.com/TrshKnn/GmailCleaner) |
| **License** | MIT |
| **Langage** | Node.js (JavaScript) |
| **Étoiles GitHub** | 1 873 ⭐ |
| **Catégorie** | [[cat-email\|Email]] |
| **Mainteneur** | Communauté |

## 📝 Description

**Gmail Cleaner** est un utilitaire Node.js conçu pour **nettoyer, archiver et supprimer en masse** des emails d'une boîte Gmail. Pensé pour les utilisateurs qui accumulent des dizaines de milliers de messages (newsletters, promotions, anciens threads) et qui veulent assainir leur boîte sans cliquer un par un sur 10 000 emails.

**Fonctionnalités** :
- **Suppression en masse** par expéditeur, label, sujet, date ou taille
- **Filtrage intelligent** : règles basées sur regex ou mots-clés
- **Mode archive** : déplace vers All Mail au lieu de supprimer (récupérable 30 jours)
- **Mode "unsubscribe"** : détecte les headers `List-Unsubscribe` et propose le désabonnement
- **Prévisualisation** : compte les emails ciblés avant action (DRY RUN)
- **Sauvegarde préalable** : export optionnel en `.mbox` via l'API
- **Quotas respectés** : throttle automatique pour ne pas dépasser les limites Gmail API

**Forces** :
- **Simple et ciblé** : un seul job, bien fait
- **API officielle Gmail** : pas de scraping, pas de risque de ban
- **Open source** : auditable, pas de fuite d'identifiants
- **Config via fichier** : règles versionnables dans un repo

**Faiblesses** :
- **Limité à Gmail** : pas d'IMAP générique (pas applicable à Outlook, Fastmail, etc.)
- **UI minimale** : CLI ou interface web basique
- **OAuth2 à configurer** : nécessite un projet Google Cloud + credentials

## 🚀 Installation

### Via Docker

```yaml
# docker-compose.yml
version: '3.8'
services:
  gmail-cleaner:
    image: ghcr.io/trshknn/gmailcleaner:latest
    container_name: gmail-cleaner
    restart: unless-stopped
    environment:
      - GOOGLE_CLIENT_ID=votre_client_id
      - GOOGLE_CLIENT_SECRET=votre_client_secret
      - REDIRECT_URI=http://localhost:8080/oauth/callback
    volumes:
      - ./config:/app/config
      - ./exports:/app/exports
    ports:
      - "8080:8080"
```

### Installation manuelle

```bash
# Prérequis : Node.js 18+
git clone https://github.com/TrshKnn/GmailCleaner.git
cd GmailCleaner
npm install
cp config.example.json config.json
# Éditer config.json avec vos credentials OAuth2
npm start
```

## ⚙️ Configuration

1. **OAuth2 Google Cloud** : créer un projet sur console.cloud.google.com, activer l'API Gmail, créer des identifiants OAuth2
2. **Scopes requis** : `https://www.googleapis.com/auth/gmail.modify` (lecture + modification + suppression)
3. **Règles de filtrage** : définir dans `config.json` les expéditeurs, labels ou patterns à nettoyer
4. **Quotas API** : Gmail impose 250 unités/seconde et 1 milliard/jour — le script throttle automatiquement
5. **Mode dry-run** : toujours tester en `dry_run: true` avant de lancer un nettoyage réel

## 🔗 Alternatives

- **[Gmail API + scripts Python](https://developers.google.com/gmail/api)** — Approche DIY plus flexible
- **[Cleanfox](https://www.cleanfox.io)** — Service commercial, interface web simple
- **[Unroll.me](https://unroll.me)** — Service commercial de désabonnement (controversé sur la revente de données)
- **[ImapCleanup](https://github.com/TrshKnn/ImapCleanup)** — À documenter : équivalent IMAP générique ?

## 🔒 Sécurité

- **Credentials OAuth2 sensibles** : ne jamais commit le fichier `config.json`, utiliser un vault (Bitwarden, Vaultwarden, SOPS)
- **Scope `gmail.modify`** : donne accès complet à la boîte, à limiter au strict nécessaire
- **Token de rafraîchissement** : stocké côté serveur, à chiffrer au repos
- **Audit** : activer les logs d'API Google pour tracer les actions
- **Sauvegarde obligatoire** : toujours exporter en `.mbox` avant une suppression massive

## 📚 Ressources

- [Repository GitHub](https://github.com/TrshKnn/GmailCleaner)
- [Documentation Gmail API](https://developers.google.com/gmail/api/guides)
- [Google Cloud Console](https://console.cloud.google.com/)
- [OAuth2 Gmail — guide](https://developers.google.com/identity/oauth2/web-server)

## Pages Liées
- [[cat-email]] — Toutes les apps Email du catalogue
- [[app-mailcow]] — Serveur mail complet self-hosted (alternative à Gmail)
- [[securisation-home-lab]] — Bonnes pratiques OAuth et secrets
- [[recettes-docker-compose]] — Templates Docker
- [[app-simplelogin]] — Générateur d'alias email anti-spam
