📧 Gmail Exporter

Профессиональный инструмент для экспорта переписки из Gmail с вложениями.

Экспортирует полные цепочки переписки, скачивает вложения, разбивает по лимиту Telegram и предоставляет детальную статистику.

✨ Возможности

Функция	Описание
🔗 Полные цепочки	Экспорт thread'ов с входящими и исходящими сообщениями
📎 Вложения	Автоматическое скачивание с пропуском существующих файлов
🎯 Фильтрация	По датам, ключевым словам, отправителям
📊 Статистика	Активность по месяцам, пиковые часы, топ собеседников
💾 Мультиформат	Экспорт в TXT, JSON, CSV
✂️ Разбивка	Автоматическое деление по лимиту Telegram (4096 символов)
🚫 Интеллектуальный фильтр	Пропуск inline-изображений (эмодзи, иконки подписи)
📝 Логирование	Подробные логи для отладки
⚙️ CLI	Аргументы командной строки для гибкой настройки

Пример вывода в консоль:

==================================================
🚀 Gmail Exporter v2.0.0
==================================================
📧 Собеседники: partner@gmail.com, client@yandex.ru
📤 Ваш email: me@gmail.com
📊 Макс. результатов: 1000
💾 Формат: txt, json

📥 Загрузка:  100%|████████████| 603/603 [01:48<00:00]
📨 Обработка: 100%|████████████| 603/603 [02:30<00:00, сообщ.=847, влож.=156]

══════════════════════════════════════════════════
📊 СТАТИСТИКА ПЕРЕПИСКИ
══════════════════════════════════════════════════
💬 Цепочек/писем: 603
📨 Всего сообщений: 847
   ├─ 📥 Входящих: 412
   └─ 📤 Исходящих: 435
📝 Символов: 156,234
📏 Средняя длина: 184 символов

📎 Вложений: 198
   ├─ Скачано: 156
   ├─ Пропущено: 42
   ├─ Общий размер: 45.2 МБ
   └─ Типы: pdf, jpg, png, docx

📅 Топ месяцев активности:
   • 2024-01: 89 сообщений
   • 2023-12: 76 сообщений
   • 2024-02: 65 сообщений

⏰ Пиковые часы:
   • 10:00 - 11:00: 67 сообщений
   • 14:00 - 15:00: 54 сообщений
══════════════════════════════════════════════════

🚀 Быстрый старт

1. Установка зависимостей

pip install -r requirements.txt

2. Получение credentials.json

Перейдите в Google Cloud Console
Создайте проект → Включите Gmail API
APIs & Services → Credentials → Create Credentials → OAuth client ID
Выберите Desktop app → Скачайте JSON
Сохраните как credentials.json рядом со скриптом

3. Настройка `config.ini`

[Gmail]
my_email = your_email@gmail.com
sender_emails = partner@gmail.com, client@yandex.ru

4. Запуск

python main.py

При первом запуске откроется браузер для авторизации.

⚙️ Конфигурация

Полный пример config.ini

[Gmail]
# Обязательные параметры
my_email = me@gmail.com
sender_emails = partner@gmail.com, client@yandex.ru

# Фильтрация
max_results = 1000
date_from = 2024-01-01
date_to = 2025-12-31
keywords = важно, проект, срочно

# Формат экспорта (txt, json, csv - можно несколько)
export_format = txt, json, csv

💻 Командная строка

# Базовый запуск
python main.py

# Тестовый запуск (без скачивания вложений)
python main.py --dry-run

# Только статистика
python main.py --stats-only

# Экспорт в JSON и CSV
python main.py --format json,csv

# Фильтр по дате
python main.py --date-from 2024-01-01 --date-to 2024-06-30

# Поиск по ключевым словам
python main.py --keywords "проект,важно"

# Подробный вывод
python main.py --verbose

# Свой файл конфигурации
python main.py --config /path/to/config.ini

# Все параметры
python main.py --help

Доступные аргументы

Аргумент	Описание
`-c, --config`	Путь к файлу конфигурации
`-f, --format`	Формат экспорта: txt, json, csv
`--date-from`	Начальная дата (YYYY-MM-DD)
`--date-to`	Конечная дата (YYYY-MM-DD)
`-k, --keywords`	Ключевые слова для поиска
`--dry-run`	Тестовый запуск без скачивания
`--stats-only`	Только статистика без файлов
`-v, --verbose`	Подробный вывод
`-l, --log-file`	Путь к файлу лога
`--max-results`	Макс. цепочек для обработки
`--version`	Версия программы

📁 Структура проекта

gmail-exporter/
├── main.py                   # Точка входа
├── gmail_exporter/           # Пакет
│   ├── __init__.py
│   ├── constants.py          # Константы, версия
│   ├── config.py             # Загрузка config.ini
│   ├── utils.py              # Логирование, форматирование
│   ├── auth.py               # OAuth 2.0 авторизация
│   ├── gmail_api.py          # Работа с Gmail API
│   ├── formatter.py          # Форматирование TXT/JSON
│   ├── statistics.py         # Статистика
│   ├── exporter.py           # Экспорт в TXT/JSON/CSV
│   └── cli.py                # Аргументы CLI
├── config.ini                # Конфигурация
├── credentials.json          # OAuth credentials (ваши)
├── token.json                # Токен доступа (генерируется)
├── requirements.txt          # Зависимости
├── README.md                 # Документация
├── LICENSE                   # MIT License
└── .gitignore                # Исключения для Git
│
├── export/                   # Папка экспорта
│   ├── attachments/          # Вложения
│   │   ├── document.pdf
│   │   └── photo.jpg
│   ├── part001.txt           # Текст (часть 1)
│   ├── part002.txt           # Текст (часть 2)
│   ├── export.json           # JSON экспорт
│   └── export.csv            # CSV экспорт
│
└── logs/                     # Логи
    └── gmail_exporter_20240115_143022.log

📄 Форматы вывода

TXT (по умолчанию)

══════════════════════════════════════════════════
💬 ПЕРЕПИСКА: "Обсуждение проекта" (3 сообщ.)
══════════════════════════════════════════════════
📥 Входящее | 15 января 2024 г., 10:30
От: partner@gmail.com → Кому: me@gmail.com

Привет! Как дела с проектом?

──────────────────────────────
📤 Исходящее | 15 января 2024 г., 11:45
От: me@gmail.com → Кому: partner@gmail.com
📎 Вложения: report.pdf

Всё готово, смотри вложение.

JSON

{
  "export_date": "2024-01-15T14:30:22",
  "threads_count": 603,
  "threads": [
    {
      "id": "18f4a2b3c1d5e6f7",
      "subject": "Обсуждение проекта",
      "messages_count": 3,
      "messages": [
        {
          "id": "18f4a2b3c1d5e6f7",
          "date": "15 января 2024 г., 10:30",
          "date_iso": "2024-01-15T10:30:00",
          "from": {"email": "partner@gmail.com", "name": "Иван Петров"},
          "to": {"email": "me@gmail.com", "name": ""},
          "subject": "Обсуждение проекта",
          "body": "Привет! Как дела с проектом?",
          "attachments": []
        }
      ]
    }
  ]
}

CSV

Табличный формат для импорта в Excel, Google Sheets, базы данных.

thread_id,subject,message_id,date,date_iso,from_email,from_name,to_email,body,attachments
18f4a2b3c1d5e6f7,Обсуждение проекта,18f4a2b3c1d5e6f7,15 января 2024 г. 10:30,2024-01-15T10:30:00,partner@gmail.com,Иван Петров,me@gmail.com,"Привет! Как дела с проектом?",
18f4a2b3c1d5e6f8,Обсуждение проекта,18f4a2b3c1d5e6f8,15 января 2024 г. 11:45,2024-01-15T11:45:00,me@gmail.com,,partner@gmail.com,"Всё готово, смотри вложение.",report.pdf

🎯 Особенности

Интеллектуальный фильтр вложений

Автоматически пропускает:

Inline-изображения (эмодзи, смайлики)
Иконки в подписи (logo.png, signature.gif)
Мелкие картинки < 10 КБ
Пропуск существующих файлов
При повторном запуске уже скачанные файлы пропускаются — можно прервать и продолжить позже.

Разбивка по лимиту Telegram

TXT файлы автоматически разбиваются на части по 4096 символов — каждый файл готов к отправке как сообщение.

🔧 Требования

Python 3.8+
Google аккаунт с доступом к Gmail
Включённый Gmail API в Google Cloud Console

Зависимости

google-auth-oauthlib>=1.2.0
google-auth-httplib2>=0.2.0
google-api-python-client>=2.100.0
tqdm>=4.66.0

🔐 Безопасность

⚠️ ВАЖНО: Никогда не публикуйте эти файлы!

Файл	Описание	Опасность утечки
credentials.json	OAuth ключи от Google Cloud	Доступ к вашему Gmail
token.json	Токен авторизации	Доступ к вашему Gmail
config.ini	Ваши email и настройки	Менее критично, но лучше не публиковать

✅ Безопасная настройка

# 1. Скопируйте примеры файлов
cp config.example.ini config.ini
cp credentials.example.json credentials.json

# 2. Заполните своими данными
nano config.ini
nano credentials.json

# 3. Файлы уже в .gitignore — они не попадут в коммиты

📋 .gitignore включает:

credentials.json
token.json
config.ini
export/
logs/

🔑 Альтернативная авторизация (IMAP)

Почему OAuth 2.0 — рекомендуемый метод?

Текущая реализация использует OAuth 2.0 через Gmail API — это официальный, безопасный и наиболее функциональный способ работы с Gmail. Авторизация в браузере требуется только один раз, затем используется сохранённый token.json.

⚠️ Обычный логин/пароль НЕ работает

С 30 мая 2022 года Google полностью отключил доступ по логину и паролю для сторонних приложений. При попытке подключиться вы получите ошибку: IMAP4.error: [AUTHENTICATIONFAILED] Invalid credentials (Failure)

Альтернатива: IMAP + App Password

Если OAuth 2.0 по каким-то причинам не подходит, можно использовать IMAP с паролем приложения (App Password). Это требует включённой двухфакторной аутентификации (2FA).

Как создать App Password:

Google Account → Security → 2-Step Verification → App passwords
Выбрать Mail и Windows Computer (или другое устройство)
Google сгенерирует 16-символьный пароль: xyzw abcd efgh ijkl

Преимущества App Password:

✅ Нет необходимости в Google Cloud Console
✅ Нет браузерной авторизации
✅ Проще для неподготовленных пользователей

⚠️ Ограничения IMAP vs Gmail API:

Функция	Gmail API (текущий)	IMAP + App Password
Thread ID (цепочки)	✅ Нативная поддержка	❌ Нет, группировка по Subject
Входящие + исходящие	✅ Полные thread'ы	⚠️ Требует IMAP Sent
Вложения	✅ Полная поддержка	✅ Есть
Метки Gmail	✅ Есть	❌ Нет
Скорость	✅ Быстро	⚠️ Медленнее
Статистика	✅ Полная	⚠️ Ограниченная
Авторизация	OAuth (браузер 1 раз)	App Password

💼 Индивидуальная доработка

Реализация IMAP + App Password возможна как индивидуальный заказ. Это потребует:

Новый модуль imap_client.py
Параметр --auth imap в CLI
Настройку app_password в config.ini
Адаптацию логики группировки сообщений в цепочки

Для обсуждения доработки свяжитесь с автором.

📜 Лицензия

MIT License - свободное использование для любых целей.

👨‍💻 Автор

Oleg Kovalev

💼 Фриланс разработчик
🐍 Python, Automation, API Integration
📧 Для заказов:
Telegram: @oleg_k79
E-mail: o.kovalyoff@gmail.com

🤝 Вклад в проект

Pull requests приветствуются! Для крупных изменений сначала откройте issue.

📋 Changelog

v2.0.0

✨ Добавлена статистика переписки
✨ Фильтрация по датам и ключевым словам
✨ Экспорт в JSON и CSV
✨ Аргументы командной строки
✨ Логирование в файл
✨ Режимы --dry-run и --stats-only
🔧 Компактный формат вывода
🔧 Интеллектуальный фильтр inline-изображений

v1.0.0

🎉 Первый релиз
📧 Экспорт писем и вложений
📎 Скачивание вложений
✂️ Разбивка по лимиту Telegram

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
gmail_exporter		gmail_exporter
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.example.ini		config.example.ini
credentials.example.json		credentials.example.json
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation