Удаление сообщений в Yandex 360

Обзор

Скрипт del_message_v3.py - это инструмент для поиска и удаления электронных писем в почтовых ящиках Yandex 360. Скрипт предоставляет комплексное решение для управления сообщениями с использованием API Yandex 360 и IMAP протокола. Поиск сообщений и их удаление происходит как обычных, так и общих почтовых ящиках. Подключение к ящику может двумя способами - от имени делегированной учётной записи, параметры которой заданы в конфигурационном файле или через временный токен, полученный с помощью сервисного приложения.

Ключевые возможности:

🔍 Поиск сообщений по Message-ID - точный поиск конкретного сообщения
📊 Автоматический поиск почтовых ящиков - через логи аудита Yandex 360
🔍 Поиск и удаление писем как в пользовательских почтовых ящиках, так и в общих
🗑️ Удаление сообщений из множества ящиков - параллельная обработка
💾 Checkpoint система - сохранение и восстановление состояния почтовых ящиков
🔐 Работа с делегированными ящиками - временное назначение прав доступа
🧪 Режим dry-run - тестирование без фактического удаления
📋 Детальные отчеты - полная информация о результатах обработки
⚡ Многопоточность - быстрая обработка множества почтовых ящиков
🎯 Интерактивное меню - удобный интерфейс командной строки

🎯 ФИНАЛЬНЫЙ ОТЧЕТ О ПОИСКЕ И УДАЛЕНИИ

После завершения работы скрипт автоматически выводит детальный отчет, содержащий:

✅ Было ли найдено сообщение в каждом почтовом ящике
📁 В каких папках найдено сообщение (например: "INBOX", "Sent", "Archive")
🗑️ Статус удаления (успешно удалено / ошибка / не найдено)
📊 Итоговая статистика по всем обработанным ящикам

Пример отчета:

====================================================================================================
ФИНАЛЬНЫЙ ОТЧЕТ О ПОИСКЕ И УДАЛЕНИИ СООБЩЕНИЯ
====================================================================================================
Искомое сообщение: <example@mail.com>

✓ СООБЩЕНИЕ НАЙДЕНО И ОБРАБОТАНО:

  Почтовый ящик: user1@example.ru
  Папки: INBOX, Sent
  Статус: Успешно удалено

  Почтовый ящик: user2@example.ru
  Папки: Archive
  Статус: Успешно удалено

Сообщение НЕ найдено в следующих ящиках:
  - user3@example.ru

----------------------------------------------------------------------------------------------------
ИТОГОВАЯ СТАТИСТИКА:
  Всего почтовых ящиков для проверки: 3
  Сообщение найдено в ящиках: 2
  Сообщение не найдено в ящиках: 1
  Пропущено ящиков: 0
  Ошибок при обработке: 0
====================================================================================================

Также программа создаёт отдельный лог с указанием сообщения, ящика и успешности удаления сообщения в соответствующем ящике.

Warning

Использовавание логов аудита для поисков почтовых ящиков (опиция меню "8 - Delete messages using audit log") доступна только на некоторых тарифах (где включены логи аудита). В остальных случаях пользуйтесь опицей удаления без поиска в логах аудита (опиця 9).

Максимальное время поиска событий в логах аудита (если они включены) - 190 дней.

Если логи аудита доступны для вашего тарифа, вы должны увидеть их в этом разделе администрирования. Если они доступны и не активированы, вы должны их активировать.

Параметры

Скрипт использует следующие переменные окружения, которые можно задать в файле .env в каталоге скрипта или непосредственно в окружении:

Имя параметра	Описание	Обязательный	Пример значения
`OAUTH_TOKEN_ARG`	OAuth-токен для аутентификации в API Yandex 360.	Да	`y0_AgAAAA...`
`ORGANIZATION_ID_ARG`	Идентификатор организации в Yandex 360 (целочисленный).	Да	`123456`
`APPLICATION_CLIENT_ID_ARG`	ID сервисного приложения	Нет (наличие зависит от параметра `RUN_MODE`)	``y0_AgAAAA..`
`APPLICATION_CLIENT_SECRET_ARG`	Секрет сервисного приложения	Нет (наличие зависит от параметра `RUN_MODE`)	``y0_AgAAAA..`
`DELEGATE_ALIAS`	Логин делегата (без домена) для доступа к делегированным ящикам.	Нет (наличие зависит от параметра `RUN_MODE`)	`i.petrov`
`DELEGATE_DOMAIN`	Домен организации для формирования email делегата.	Нет (наличие зависит от параметра `RUN_MODE`)	`example.ru`
`DELEGATE_PASSWORD`	Пароль приложения для доступа делегата к IMAP.	Нет (наличие зависит от параметра `RUN_MODE`)	`app_password_here`
`CHECK_DIR`	Каталог для сохранения состояния почтовых ящиков (checkpoint файлы).	Нет (по умолчанию `mailbox_checkpoints`)	`mailbox_checkpoints`
`DRY_RUN`	Режим "сухого прогона" (`true` для имитации удаления, `false` для реального).	Нет (по умолчанию `false`)	`true` или `false`
`MAILBOXES_LIST_FILE`	Имя файла со списокм почтовых ящиков для поиска сообщений	Нет (по умолчанию `mailboxes.csv`)	`mailboxes.csv`
`MESSAGES_LIST_FILE`	Имя файла со списоком данных для поиска сообщений	Нет (по умолчанию `message-ids.csv.csv`)	`message-ids.csv`
`REPORTS_DIR`	Каталог для создания файлов отчёта	Нет (по умолчанию `reports`)	`reports`
`RUN_MODE`	Режим запуска скрипта	Да (`delegate`, `service_application`, `hybrid`)	`hybrid`

Примечания к параметрам

Переменные окружения: Все обязательные параметры (OAUTH_TOKEN_ARG, ORGANIZATION_ID_ARG, RUN_MODE) должны быть заданы. При их отсутствии скрипт завершится с кодом 1.
Формат даты: Поддерживаются форматы DD-MM-YYYY, DD.MM.YYYY, DD/MM/YYYY, YYYY-MM-DD, YYYY/MM/DD, MM/DD/YYYY, DD-MM-YY, YYYY.MM.DD, а также текстовые форматы на английском (например, 25 December 2023).
DRY_RUN: Если DRY_RUN=true, скрипт только имитирует удаление, логируя действия без фактического изменения почтовых ящиков.

Файл .env: Пример файла .env:

OAUTH_TOKEN_ARG=y0_AgAAAA...
ORGANIZATION_ID_ARG=123456
APPLICATION_CLIENT_ID_ARG = f1e4386f276643
APPLICATION_CLIENT_SECRET_ARG = 333bf50d7a8
DELEGATE_ALIAS=i.petrov
DELEGATE_DOMAIN=example.ru
DELEGATE_PASSWORD=app_password_here
CHECK_DIR=mailbox_checkpoints
DRY_RUN=false
MAILBOXES_LIST_FILE = mailboxes.csv
MESSAGES_LIST_FILE = message-ids.csv
REPORTS_DIR = reports
RUN_MODE = hybrid

Режимы работы скрипта

Описание режимов

Скрипт может производить аутентификацию в IMAP почтовом ящике или через делегированную учетную запись, или через токены сервисного приложения. Скрипт может работать как с одним способом, так и с двумя сразу. Каждый способ имеет свои преимущества. Аутентфиикация через делегированную учётную запись позволяет:

подключаться к Общим ящикам (недоступно для токенов сервисного приложения);
подключаться к заблокированным ящикам (недоступно для токено сервисного приложения). Однако недостатком работы с делегированным ящиком является медленная скрорость обработки (примерно в два раза медленнее, чем для токенов сервисного приложения, так как необходимо выполнять действия по добавлению и удалению делегата в каждый ящик для поиска и удаления сообщения). Поэтому добавлен режим hybrid, при котором необходимо иметь как настроенную учётную запись делегата (DELEGATE_ALIAS,DELEGATE_DOMAIN, DELEGATE_PASSWORD), так и корректно настроенное сервисное приложение (APPLICATION_CLIENT_ID_ARG, APPLICATION_CLIENT_SECRET_ARG).

КРАТКО о режимах работы

Если вы владеете учётной записью владельца организации и вам важна скорость работы скрипта:

создайте сервисное приложение, настройте его через скрипт;
укажите учётку делегата (любая учётка в организации Я360, для которой возможно получить пароль приложения для IMAP протокола);
пропишите параметры сервисного приложения и делегата в .env и в RUN_MODE укажите hybrid.

Скорость работы в разных режимах

В тестовой среде работа через делегированную учётную запись удаляет сообщения со средней скоростью 3-4 секунды на один ящик. Работа через сервисное приложение - около 2 секунд на ящик.

Во всех остальных случаях укажите параметры делегата (например, свою учётку в Я360) и в RUN_MODE укажите delegate.

Требования к запуску скрипта со стороны Яндекс 360 API

Для работы скрипта необходимо:

Получить токен OAuth для чтения данных организации Яндекс 360 через API.

Получение токена OAuth для работы с данными Яндекс 360

Для работы приложения необходимо сгенериовать OAuth токен для аутентификации в API Яндекс 360. Токен должен содержать необходимые права для выполения операций управления ресурсами в организации Яндекс 360. Документация - Создание приложения. Последовательность шагов для создания токена:

заходим на https://oauth.yandex.ru/client/new/. Аутентифицируемся от имени администратора организации Яндекс 360.
Заполняем поля в форме создания приложения:
- Поле "Название вашего сервиса" - произвольное название.
- Включаем галочку "Веб сервисы"
- В поле Redirect URL вводим https://oauth.yandex.ru/verification_code
- В разделе "Почта для связи" указываем свой email.

Добавляем разрешения для токена. Для этого в разделе "Доступ к данным" ищем и добавляем следующие разрешения:

Имя разрешения	Что можно делать
directory:read_users	читать информацию о пользователях
ya360_security:audit_log_mail	чтение событий аудит лога Почты
ya360_admin:mail_read_shared_mailbox_inventory	листинг делегирования ящика и чтение общих ящиков
ya360_admin:mail_write_shared_mailbox_inventory	управление делегированием почтовых ящиков
(опционально) ya360_security:service_applications_read	чтение сервисных приложений (для режима `hybrid`)
(опционально) ya360_security:service_applications_write	запись сервисных приложений (для режима `hybrid`)

нажимаем на кнопку "Создать приложение".
Свойства созданного приложения отображаются в новом окне "Мои приложения". Ищем раздел с идентификатором созданного приложения и копируем строку из поля "ClientID":
В текстовом редакторе созадем строку вида https://oauth.yandex.ru/authorize?response_type=token&client_id=<идентификатор приложения> и вставляем в ней вместо <идентификатор приложения> скопированное значение ClientID из предыдущего пункта. Вставляем получившуюся ссылку в браузер и нажимаем "Enter".

Warning

Копируем токен и сохраняем в надёжном месте.

Получить ID организации в Яндекс 360. Для этого необходимо зайти в консоль администрирования и в левом нижнем углу интерфейса будет необходимый номер.
Записываем полученные на предыдущем шаге OAuth токен и Org ID в соответствующие переменные в файле файле .env в том же каталоге, что и сами скрипты. Эта информация нужна для правильной аутентификации скриптов в API Яндекс 360.

Создание сервисного приложения

Для работы скрипта через сервисное приложение (RUN_MODE = hybrid) необходимо наличие в правах основного токена прав:

ya360_security:service_applications_read
ya360_security:service_applications_wwrite

После этого необходимо создать ещё одно OAuth приложение, шаги по созданию аналогичны шагам создания основного приложения. Но при указании доступных разрешений нужно указать:

mail:imap_full

После сохранения приложения нужно скопировать его Application ID и APPLICATION Secret, которые необходимо записать в соответствующие параметры в конфигурационном файле (APPLICATION_CLIENT_ID_ARG, APPLICATION_CLIENT_SECRET_ARG).

Warning

Для корректной настройки сервисного приложения токен основного приложения необходимо выписывать от имени учётки-владельца организации (в домене @yandex.ru).

При первом запуске скрипта необходимо перейти в пункт меню 4. Проверить/настроить сервисное приложение для удаления сообщений. и затем выбрать 2. Настроить сервисное приложение.. Это корректно настроит сервисное приложение для работы скрипта.

Установка

Системные требования

Python: версия 3.9 или выше
Операционная система: Linux, macOS, Windows
Память: минимум 512 МБ RAM
Сеть: доступ к api360.yandex.net, oauth.yandex.ru, imap.yandex.ru
Права: права владельца организации Yandex 360 (для настройки)

Шаг 1: Установка Python и зависимостей

Linux/macOS:

# Проверьте версию Python
python3 --version

# Если Python не установлен или версия < 3.7:
# Ubuntu/Debian:
sudo apt update && sudo apt install python3 python3-pip

# macOS (с Homebrew):
brew install python3

# Клонируйте или скачайте репозиторий
cd /path/to/project

# Установите зависимости
pip3 install -r requirements.txt

# Или установите вручную:
pip3 install python-dotenv requests python-dateutil aioimaplib

Windows:

# Скачайте Python с python.org (версия 3.7+)
# Убедитесь, что установлен pip

# Откройте PowerShell или CMD в папке проекта
cd C:\path\to\project

# Установите зависимости
pip install -r requirements.txt

# Или установите вручную:
pip install python-dotenv requests python-dateutil aioimaplib

Сценарии использования

Скрипт поддерживает различные сценарии работы в зависимости от ваших задач.

Сценарий 1: Удаление недавнего сообщения (< 90 дней)

Задача: Удалить спам-рассылку, которая была отправлена всем сотрудникам организации 2 дня назад.