# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

ИМЯ ОБРАЩИТЕЛЯ: электронная почта
Отправка электронной почты через Gmail API со встроенной защитой от черновиков.

ОПИСАНИЕ:
Обработчик электронной почты обеспечивает безопасную отправку электронной почты через API Gmail.
Каждое электронное письмо сначала создается как черновик и должно быть явно помечено словом «подтвердить».
должно быть подтверждено перед отправкой. Это предотвращает случайные
Отправка электронной почты.

ОПЕРАЦИИ:

  send <to> <subject> <body> Создать черновик (основная команда)
    Опции: --cc <электронная почта>, --bcc <электронная почта>, --attach <путь к файлу>

  черновик <кому> <тема> <тело> Псевдоним для отправки

  подтвердите <id> Подтвердите и отправьте черновик
    Опции: --by <имя>

  отменить <id> Отменить (удалить) черновик

  черновики Список открытых черновиков
    Псевдоним: список (пустая команда также показывает черновики)

  отправлено Показать отправленные письма

  show <id> Показать детали черновика
    Показывает полный текст, получателя, копию/скрытую копию, статус

  настройка Gmail API Расширение областей (однократно)
    Требуется аутентификация OAuth2 только для чтения + отправка 

  test Отправьте тестовое письмо на свой адрес

  help Показать этот текст справки

ПРИМЕРЫ:

  1. Создайте черновик с позиционными аргументами:
     bach email send user@example.com "Betreff" "Hallo Welt"

  2. Черновик с именованными аргументами:
     bach email send user@example.com --subject "Meeting" --body "Termin: 14:00"

  3. С CC и вложением:
     bach email send user@example.com \
       --тема «Отчет» \
       --body "Просмотреть файл" \
       --cc admin@example.com\
       --attach C:\documents\report.pdf

  4. Отправить черновик:
     bach email confirm 42

  5. Отменить черновик:
     bach email cancel 42

  6. Просмотрите все открытые черновики:
     bach email drafts

ФАЙЛЫ:

  Hub/email.py Этот обработчик (класс EmailHandler)
  _services/mail/email_sender.py Интеграция Gmail API, управление черновиками
  _services/mail/account_manager.py управление токенами OAuth2
  data/bach.db Метаданные локальной электронной почты (черновики записей)

БЕЗОПАСНОСТЬ:

  - Модель черновика: каждое электронное письмо сначала сохраняется как черновик.
  - Явное подтверждение: фактически отправляется только слово «подтвердить».
  - Области действия токена: только чтение + отправка (Gmail API oauth2)
  - Обработка ошибок: ошибки регистрируются в базе данных (показать <id> показывает подробности)

КОНФИГУРАЦИЯ:

  Учетная запись: контролируется через ~/.config/paper_publisher/config.json или
           локальные токены OAuth2 в _services/mail/tokens/

ОБРАБОТКА ОШИБОК:

  - Неверные адреса электронной почты немедленно отклоняются.
  - Будет сообщено об отсутствующей теме/тексте.
  - Ошибки Gmail регистрируются с указанием темы и идентификатора.
  - Черновик можно отменить в любой момент, нажав кнопку «Отмена»

СМОТРИ ТАКЖЕ:

  docs/help/base.txt Базовый класс обработчика
  docs/help/telegram.txt Интеграция Telegram для удаленного управления
  _services/mail/README.md Руководство по настройке API Gmail
