Работа с инструментом

Здесь объясняется, как устроена команда и как инструментом пользуется агент. Прочитайте это перед первой командой.

Сначала профильCopy Anchor Link

Профиль — имя, которое вы выбираете для одного аккаунта. Это первое слово каждой команды, которая работает с аккаунтом:

mail ya folders list

MAIL_PROFILE=ya делает то же для одного сеанса оболочки. Профиль никогда не подставляется сам, даже единственный: команда без профиля останавливается с кодом выхода 2 и показывает профили на этом компьютере.

Подключить почтовый ящикCopy Anchor Link

Сначала подготовьте ящик: включите IMAP и создайте пароль приложения. Шаги для каждого провайдера описаны в подготовке почтового ящика, их же печатает session start.

mail ya session start --address [email protected] # new profile: finds the server, shows the steps, asks for the app password
mail ya session start                 # an existing profile: asks for the app password again (checked, kept in the keyring)
mail ya account check                 # logs in and lists what the server supports
mail ya folders list                  # folders with role and counts
mail ya sync --since-time 2026-10-01  # reads new mail into the shared store; stored mail is skipped

session start для нового профиля должен найти почтовый сервер. Сначала он смотрит во встроенную таблицу (Яндекс, Gmail, iCloud, Mail.ru, Fastmail, Outlook). Затем смотрит запись MX домена. Затем спрашивает список почтовых серверов Thunderbird и собственный файл настроек домена. Если сервер не известен никому из них, задайте его сами через --host, --port и --security или назовите провайдера из таблицы: --provider yandex.

В терминале session start спрашивает то, чего не хватает: провайдера и адрес. Без терминала он ничего не спрашивает. Отсутствие --address или пароля тогда — ошибка, а пароль он читает из MAIL_PASSWORD. Профиль сохраняется только после того, как сервер принял пароль приложения. Outlook принимает для IMAP только OAuth, поэтому session start пока его отклоняет. Чтобы сменить сервер существующего профиля, используйте config set или новое имя профиля.

session start берёт пароль из терминала или из MAIL_PASSWORD. Из параметра или ссылки он его никогда не берёт. После того как сервер принял пароль, mail хранит его в системной связке ключей. Если связка ключей не работает, mail хранит его в закрытом файле и один раз сообщает об этом в stderr. --credential-storage file выбирает файл; мы этого не рекомендуем. Если у mail нет пароля, он читает тот, что оставила Himalaya (secret-tool, служба himalaya, аккаунт — имя профиля). Тогда существующей настройке Himalaya новый пароль не нужен.

sync читает INBOX и папку Sent. Другие папки задают --folder или настройка folders профиля. Он читает сначала самую новую почту. --limit ограничивает число новых писем за один запуск. --rescan заново перечисляет всё окно. Он сохраняет только текст и заголовки. Вложения он не хранит.

Большой ящик не помещается в один запуск. У sync есть бюджет запросов к серверу, рассчитанный на его срок: 15 минут в терминале, 45 секунд через MCP. --timeout меняет срок. --max-pages уменьшает бюджет. Запуск сохраняет прочитанное, затем отвечает state: partial и выдаёт ту же команду в next. Выполните её снова, чтобы продолжить. mail <profile> status показывает, как далеко ушла синхронизация.

Яндекс не выдаёт id сообщения. Для такого сервера sync перечисляет только номер, флаги, дату и размер каждого сообщения, а каждое новое сообщение скачивает один раз. Сохранённую почту он пропускает по этому номеру, так что повторный запуск ничего не читает дважды. Он не замечает почту, удалённую на сервере, и изменённые флаги у пропущенных сообщений. --rescan учитывает и то и другое.

Иногда сервер не может ответить по одному сообщению (Яндекс отвечает так на некоторые с NO [UNAVAILABLE]). sync запрашивает его ещё раз в конце запуска. Если сбой повторяется, sync учитывает сообщение в unreadable и оставляет его до следующего запуска.

Иногда сервер закрывает соединение. sync ждёт 1, затем 3, затем 10 секунд, с небольшим случайным разбросом, чтобы много запусков не повторяли попытку одновременно. Затем он переподключается. Он проверяет, что сервер по-прежнему нумерует почту папки так же, и продолжает с неудавшегося запроса, пока позволяют бюджет и срок. Если сбой повторяется, ответ сохраняет собственный код сетевой ошибки как cause_code, и mail runs show его показывает.

Вывод для скриптовCopy Anchor Link

Каждая команда, кроме mcp serve на stdin и stdout, принимает --json и печатает одно значение JSON в stdout. Ошибки — JSON в stderr, с кодом, по которому можно ветвиться. В справочнике команд коды перечислены.

АгентыCopy Anchor Link

mail skill install кладёт навык инструмента туда, где его ищут Claude Code, Codex, Gemini CLI и OpenClaw. mail skill install --for hermes также добавляет эту папку в собственные настройки Hermes Agent, поэтому простая skill install Hermes не затрагивает. mail personal mcp serve отдаёт команды профиля по MCP, через stdin и stdout:

claude mcp add mail -- mail personal mcp serve

Сервер предлагает все команды. Команда, которая пишет, пишет только в локальное хранилище, никогда не в почтовый ящик. Что выполнится, решают разрешения профиля; см. настройки.

Для ChatGPT и Claude в браузере mail personal mcp serve --http --public-url https://laptop.example.ts.net работает на 127.0.0.1 (порт 8765 или --port) за вашим собственным туннелем. Браузерное приложение входит по одноразовому коду, который печатает команда; mail personal mcp revoke завершает все входы. mail personal mcp server start запускает тот же сервер в фоне, mcp server status показывает его порт, код входа и вошедшие приложения, а mcp server stop его останавливает.

Поиск по почтеCopy Anchor Link

mail наполняет общее хранилище. memo ищет в нём и показывает его содержимое:

memo search mail "invoice"

Слова запроса описаны в memo search.