# Работа с инструментом (/ru/docs/mail/usage) Здесь объясняется, как устроена команда и как инструментом пользуется агент. Прочитайте это перед первой командой. ## Сначала профиль [#сначала-профиль] Профиль — имя, которое вы выбираете для одного аккаунта. Это первое слово каждой команды, которая работает с аккаунтом: ```sh mail ya folders list ``` `MAIL_PROFILE=ya` делает то же для одного сеанса оболочки. Профиль никогда не подставляется сам, даже единственный: команда без профиля останавливается с кодом выхода 2 и показывает профили на этом компьютере. ## Подключить почтовый ящик [#подключить-почтовый-ящик] Сначала подготовьте ящик: включите IMAP и создайте пароль приложения. Шаги для каждого провайдера описаны в [подготовке почтового ящика](/llms.mdx/docs/ru/mail/providers/content.md), их же печатает `session start`. ```sh mail ya session start --address me@example.com # 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 status` показывает, как далеко ушла синхронизация. Яндекс не выдаёт id сообщения. Для такого сервера `sync` перечисляет только номер, флаги, дату и размер каждого сообщения, а каждое новое сообщение скачивает один раз. Сохранённую почту он пропускает по этому номеру, так что повторный запуск ничего не читает дважды. Он не замечает почту, удалённую на сервере, и изменённые флаги у пропущенных сообщений. `--rescan` учитывает и то и другое. Иногда сервер не может ответить по одному сообщению (Яндекс отвечает так на некоторые с `NO [UNAVAILABLE]`). `sync` запрашивает его ещё раз в конце запуска. Если сбой повторяется, `sync` учитывает сообщение в `unreadable` и оставляет его до следующего запуска. Иногда сервер закрывает соединение. `sync` ждёт 1, затем 3, затем 10 секунд, с небольшим случайным разбросом, чтобы много запусков не повторяли попытку одновременно. Затем он переподключается. Он проверяет, что сервер по-прежнему нумерует почту папки так же, и продолжает с неудавшегося запроса, пока позволяют бюджет и срок. Если сбой повторяется, ответ сохраняет собственный код сетевой ошибки как `cause_code`, и `mail runs show` его показывает. ## Вывод для скриптов [#вывод-для-скриптов] Каждая команда, кроме `mcp serve` на stdin и stdout, принимает `--json` и печатает одно значение JSON в stdout. Ошибки — JSON в stderr, с кодом, по которому можно ветвиться. В [справочнике команд](/llms.mdx/docs/ru/mail/commands/content.md) коды перечислены. ## Агенты [#агенты] `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: ```sh claude mcp add mail -- mail personal mcp serve ``` Сервер предлагает все команды. Команда, которая пишет, пишет только в локальное хранилище, никогда не в почтовый ящик. Что выполнится, решают разрешения профиля; см. [настройки](/llms.mdx/docs/ru/mail/configuration/content.md#permissions). Для 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` его останавливает. ## Поиск по почте [#поиск-по-почте] `mail` наполняет общее хранилище. [memo](https://github.com/WireCatLabs/cli-memo) ищет в нём и показывает его содержимое: ```sh memo search mail "invoice" ``` Слова запроса описаны в [memo search](https://github.com/WireCatLabs/cli-memo/blob/main/docs/search.md).