Входящая почта¶

Когда входящая почта включена, клиенты и сотрудники отвечают на письма Helpdesk Pro, просто отвечая на них, а новое письмо на адрес поддержки открывает заявку. Эта страница описывает приёмники, адреса ответа, то, как письмо находит свою заявку, как очищаются ответы, и журнал входящей почты.

Перед началом¶

• Входящей почте нужен плагин Email 5.3.0 или новее. Со старым плагином Email всё остальное продолжает работать: Operations → Email говорит «Inbound email needs Email plugin 5.3.0 or later», а webhook отвечает 503, чтобы провайдеры сохраняли письмо и повторяли попытку.
• Исходящая почта работает, и email.support_address задан.
• Cron запускает планировщик Grav (см. Задания и cron).

Настройка входящей почты¶

1. Установите email.support_address в адрес, на который пишут клиенты, или inbound.address, когда почта приходит на другой адрес (см. Какой адрес). Без любого из них письмо на адрес поддержки не распознаётся как письмо самой службы поддержки.
2. На странице настроек плагина откройте Email & Notifications → Inbound Email. Включите inbound.enabled и выберите приёмник (inbound.receiver, ниже).
3. Установите inbound.secret в не менее чем 32 случайных символа, например вывод openssl rand -hex 24. Секрет — часть адреса webhook и единственное, что его защищает, поэтому обращайтесь с ним как с паролем.
4. В рабочей области откройте Operations → Email, скопируйте адрес webhook и вставьте его в настройки входящей почты провайдера, следуя шагам рядом.
5. Отправьте письмо на адрес поддержки. Оно появляется в Operations → Inbound log через секунды и открывает заявку.

Чтобы Helpdesk Pro читал почтовый ящик вместо получения webhook, установите приёмник imap и см. Чтение ящика по IMAP.

Приёмники¶

generic и cloudflare всегда принимаются по адресу webhook наряду с выбранным приёмником, поэтому тест через curl работает с любым провайдером. inbound.signing_secret — их секрет HMAC; если оставить пустым, используется inbound.secret. Секрет подписи короче 32 символов указывается как проблема, и приёмник отказывает каждому запросу, пока он не станет длиннее или не будет очищен.

Адрес webhook¶

Адрес — {site}{inbound.route}/{receiver}/{inbound.secret}, например https://example.com/_helpdesk/inbound/postmark/9f6c…. Он отвечает раньше, чем Grav строит страницу, поэтому остаётся быстрым на загруженном сайте.

• Mailgun: используйте адрес, заканчивающийся на /mime (Operations → Email показывает его так). Маршрут Mailgun, пересылающий на URL, заканчивающийся на mime, отправляет всё исходное письмо, что сохраняет вложения и заголовки группировки точно как отправлено.
• Amazon SES через SNS: подтверждение подписки запрашивается автоматически (только с хоста Amazon), а письмо, которое SES помечает как содержащее вирус, отклоняется до чтения. Сообщение, сохранённое SES в S3, забирается позже заданием inbound.fetch.
• Resend: его webhook несёт только id, поэтому сообщение забирается позже заданием inbound.fetch.

Строка запроса никогда не участвует в сопоставлении, поэтому провайдер, добавляющий свои параметры, всё равно доходит до эндпоинта.

Тестовое письмо через curl¶

Подпишите исходное письмо через SignedRawReceiver::sign() плагина Email:

use Grav\Plugin\Email\Providers\Inbound\Receivers\SignedRawReceiver;

$raw = file_get_contents('reply.eml');
$signature = SignedRawReceiver::sign($raw, $signingSecret); // "t=…,v1=…"

curl -X POST "https://example.com/_helpdesk/inbound/generic/$SECRET" \
  -H "Content-Type: message/rfc822" \
  -H "X-Grav-Signature: $SIGNATURE" \
  -H "X-Grav-Envelope-To: support+t8f2k@example.com" \
  --data-binary @reply.eml

Try an email в рабочей области (ниже) выполняет пробный запуск, ничего не отправляя.

Со своего почтового сервера¶

Псевдоним Postfix или Exim может передавать каждое письмо прямо в inbound:feed, который читает его из стандартного ввода:

support: "|/var/www/example.com/bin/plugin helpdesk-pro inbound:feed --no-process --to support@example.com"

inbound:feed завершается с 75 (временный сбой), когда письмо не удалось сохранить или плагин Email слишком старый, чтобы почтовый сервер сохранил письмо и повторил попытку. См. CLI.

Чтение ящика по IMAP¶

Когда у вашего почтового провайдера нет входящего webhook, Helpdesk Pro может сам читать ящик: Gmail или Google Workspace с паролем приложения, Fastmail, iCloud или ящик, прилагавшийся к хостингу. Новая почта идёт через тот же конвейер, что и почта из webhook, поэтому группировка, защита от циклов, токены ответа сотрудников и журнал входящей почты работают одинаково.

Webhook — лучший выбор, когда он есть: он доставляет за секунды и не требует хранить пароль на сайте. IMAP — простой путь для небольшого сайта с существующим ящиком.

1. Используйте ящик, который читает только служба поддержки, например support@example.com. Helpdesk Pro помечает импортированное как прочитанное, поэтому человек, читающий тот же ящик, пропустит почту.
2. Создайте для него пароль приложения. Gmail и Google Workspace сначала требуют двухэтапную проверку, затем Google Account → Security → App passwords. У Fastmail и iCloud то же самое в настройках безопасности.
3. В Email & Notifications → Inbound Email включите inbound.enabled и установите inbound.receiver в imap.
4. В разделе IMAP Mailbox заполните inbound.imap.host (imap.gmail.com), inbound.imap.username (полный адрес) и inbound.imap.password (пароль приложения).
5. Запустите bin/plugin helpdesk-pro imap:poll --work один раз. Он читает ящик сейчас, обрабатывает найденное и печатает результат или ошибку сервера.

Опрос — повторяющееся задание imap.poll, назначаемое каждые inbound.imap.interval_seconds, пока входящая почта включена, приёмник — imap и задан хост. Адреса с плюсом (support+t8f2k@example.com) доставляются в тот же ящик Gmail, Fastmail, iCloud и большинством хостов, а токен сохраняется в заголовке To:.

Как работает опрос:

• Забирается только почта, пришедшая после первого опроса. Первый опрос берёт непрочитанную почту, а каждый следующий — каждое сообщение новее последнего импортированного, до 50 за раз.
• Каждое письмо сохраняется, затем помечается прочитанным и перемещается в inbound.imap.processed_folder, когда он задан (папка создаётся, если её нет). Сбой повторяет не более одного письма, и оно распознаётся как уже полученное.
• Если сервер перенумеровывает ящик (после некоторых миграций), опрос снова начинается с непрочитанной почты, а уже полученные письма пропускаются.
• Письмо больше inbound.max_bytes не скачивается. Оно записывается как rejected (too_large) и помечается прочитанным.
• Неудача подключения или входа ждёт 15 минут до следующей попытки. После третьей неудачи подряд администраторы получают уведомление imap_failed в колокольчике. Следующий успешный опрос сбрасывает счётчик.

Клиент IMAP — собственный клиент плагина Email (чистый PHP, без ext-imap). Он проверяет сертификат сервера, а с starttls никогда не откатывается к простому тексту.

Что происходит с письмом¶

Webhook, IMAP и inbound:feed заканчивают в одном месте. Каждое письмо сначала сохраняется (его исходные байты и строка в журнале входящей почты), а затем обрабатывается заданием inbound.process, обычно в ту же секунду.

Одно и то же письмо, пришедшее дважды (повтор провайдера, одно письмо на два ваших адреса, повторно полученное сообщение IMAP), сохраняется один раз и распознаётся по Message-ID, id провайдера или байтам. Обработку тоже безопасно повторять.

Обработка выполняет эти шаги по порядку, и первый, который принимает решение о письме, её заканчивает:

1. Защита от циклов отбрасывает почту, которую не написал человек.
2. Адрес отписки (support+u{token}@…) отписывает отправителя.
3. Отправитель находится, и сотрудники отличаются от клиентов.
4. Заявка находится или открывается новая.
5. Ответ очищается (см. Как очищаются ответы).
6. Сообщение добавляется через те же сервисы, что использует ответ в рабочей области или портале, поэтому активность, уведомления, обновления в реальном времени и письма клиентам идут как обычно.

Защита от циклов¶

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

Кто отправил¶

Отправитель — адрес From письма.

• Адрес, которого Helpdesk Pro никогда не видел, — новый клиент. Запись человека создаётся, только если для него открывается заявка.
• Почта заблокированного человека отклоняется (blocked).
• Сотрудники остаются сотрудниками только со своим токеном ответа. Письма-уведомления сотрудникам несут адрес ответа, выданный этому сотруднику. Письмо на него от этого сотрудника публикуется от его имени: публичный ответ, когда уведомление было об ответе или заявке, и внутренняя заметка, когда оно было о заметке. Любое другое письмо от сотрудника обрабатывается как письмо клиента, поэтому клиент никогда не сможет добавить внутреннюю заметку по почте.
• Ответ сотрудника, отправителя которого не удалось проверить (DMARC не прошёл или при отсутствии результата DMARC не прошли ни DKIM, ни SPF), удерживается (unverified_staff) вместо публикации. Администратор отпускает его из журнала входящей почты, когда убедится, что оно настоящее.
• Неизвестный отправитель, пишущий на адрес заметки сотрудника, отклоняется (token_mismatch).

Какая заявка¶

Совпадение используется, только когда отправитель может добавить в эту заявку: он её заявитель или копия, токен выдан ему или (при inbound.cc_join) вы писали ему об этом. Любой другой, пишущий в переписку (пересланное письмо, человек, никогда в ней не участвовавший), открывает собственную новую заявку. Почта объединённой заявки идёт в заявку, с которой её объединили; удалённая заявка не совпадает ни с чем.

Ответ на решённую заявку открывает её снова. Ответ на закрытую заявку открывает новую, чья первая активность ссылается на закрытую. Ответ сотрудника на заявку, к которой у него больше нет доступа, отклоняется (no_access); ответ клиента становится новой заявкой.

Новые заявки по почте¶

Новая заявка идёт в проект, чей почтовый псевдоним (Setup → Projects) есть в To, Cc или конверте письма, иначе в inbound.default_project (слаг проекта), иначе в первый проект. Один адрес может открыть не более inbound.new_tickets_per_sender_per_hour заявок по почте в час (new_ticket_rate). При inbound.cc_join другие люди из To и Cc письма становятся копиями новой заявки. Клиент получает подтверждение client-received, пока включён email.acknowledge_email_tickets.

Обязательные пользовательские поля не проверяются для заявок, пришедших по почте.

Вложения и встроенные изображения¶

Вложения следуют тем же правилам, что загрузки (attachments.enabled, разрешённые расширения и attachments.max_mb, см. Вложения), не более inbound.max_attachments из одного письма. winmail.dat (обёртка TNEF Outlook) и небольшие встроенные изображения, которые сохранённый текст не показывает (логотипы подписи меньше 2 КБ), пропускаются. Каждый пропущенный файл и причина перечислены в журнале входящей почты.

Подтверждение client-received для обращения, открытого по почте, говорит, какие файлы пришли и почему каждый непринятый файл не сохранён: «too large (limit 25 MB)», «that file type isn't accepted», «too many files (limit 20)», «files aren't accepted by email» или «the file couldn't be read».

Изображение, вставленное в письмо (встроенное вложение cid:), сохраняется со своим content id и показывается на месте сообщения в рабочей области и портале через те же маршруты файлов с проверкой доступа, что и любой файл. Никто никогда не видит адрес cid:. Читатель, которому нельзя открыть файл, видит только его имя.

Адреса ответа¶

Пока входящая почта включена и может принимать, каждое письмо Helpdesk Pro о заявке просит отвечать на адрес, сделанный для этого получателя и заявки:

Reply-To: support+t4k2qz7mfa9xw3hb@example.com
List-Unsubscribe: <https://example.com/help/unsubscribe?p=…>, <mailto:support+u4k2qz7mfa9xw3hb@example.com?subject=unsubscribe>

Часть после +t — токен ответа: 16 случайных букв и цифр, выдаваемых при первом письме человеку о заявке и повторно используемых во всех дальнейших письмах о ней. Один токен находит заявку и человека, поэтому ответ совпадает, даже когда почтовое приложение отбросило заголовки группировки. Он же делает ответ сотрудника ответом сотрудника.

Чтобы ответить на заявку из дайджеста, откройте её и ответьте там или ответьте на собственное уведомление этой заявки. Токены staff, note и digest выдаются только сотрудникам с учётной записью на сайте. Клиент всегда получает только токен client.

Почта на адрес +u{token} отписывает своего человека: токен клиента останавливает письма об этом обращении, а токен сотрудника выключает всю почту Helpdesk этого сотрудника.

Какой адрес¶

Адрес, в который попадает токен, — первый из заданных:

1. inbound.address: задайте его, когда почта приходит на другой адрес, чем тот, с которого вы отправляете, например на адрес Cloudflare Email Routing или отдельный входящий домен.
2. Почтовый псевдоним проекта заявки, поэтому ответы о заявке Billing идут на billing+t…@.
3. email.support_address.
4. Адрес, с которого отправляется почта (email.from_address, затем From плагина Email).

Ваш провайдер или почтовый сервер должен доставлять почту для {local}+anything@{domain} туда же, куда {local}@{domain}:

• Cloudflare Email Routing: включите субадресацию (Email Routing → Settings). Тогда support+t…@example.com следует правилу support@example.com.
• Amazon SES: получатель правила получения support@example.com также совпадает с support+anything@example.com.
• Входящие webhook других провайдеров: направьте на webhook весь входящий домен или маршрут, совпадающий с формой с плюсом.
• Свой почтовый сервер или ящик IMAP: убедитесь, что +detail доставляется в основной ящик (Postfix recipient_delimiter = +; большинство хостинговых ящиков делает это по умолчанию).

Без адресации с плюсом¶

Почтовая система, отклоняющая или удаляющая адреса +detail, не может нести токен. Установите inbound.plus_addressing в false, и Helpdesk Pro не будет помещать токен ни в один адрес. Ответы всё равно находят заявку через заголовки группировки и скрытый маркер ref:, чего достаточно почти для любого почтового приложения.

Что вы теряете: ответ из приложения, отбрасывающего оба, не находит заявку и открывает новую, ответы сотрудников по почте обрабатываются как письма клиентов, а отписки по почте нет.

Когда ничего не меняется¶

При выключенном inbound.enabled, плагине Email старше 5.3.0 или отсутствии способа получить почту (нет секрета webhook длиной 32 символа или больше либо приёмник imap без хоста) почта отправляется точно так, как если бы входящей не существовало: без Reply-To, без отписки по mailto, без выданных токенов, а письмо клиенту говорит «View or reply to your request».

Как очищаются ответы¶

Ответ по почте несёт больше, чем новые слова: предыдущую переписку, цитируемую ниже, подпись, «Sent from my iPhone». Helpdesk Pro сохраняет только то, что человек написал на этот раз, поэтому заявка читается как переписка. Сообщение точно в том виде, в каком оно пришло, тоже всегда сохраняется за Show original.

Helpdesk Pro использует текстовую часть, когда в ней есть слова, поскольку обычный текст уже является допустимым Markdown. Он прибирает остатки ссылок Apple Mail (https://example.com <https://example.com/> становится одной ссылкой) и превращает его невидимые метки изображений во встроенные изображения. Когда пригодной текстовой части нет, HTML-часть преобразуется в Markdown.

Преобразование никогда не сохраняет ничего, что читатель не мог бы увидеть или что обратилось бы к другому серверу: <style>, <script>, <head> и скрытые элементы отбрасываются; ссылка javascript: сохраняет только свой текст; изображения, загружаемые из сети, сохраняют только alt-текст, поэтому отслеживающее изображение из письма клиента никогда не запрашивается, когда сотрудники читают заявку; изображения 1×1 отбрасываются.

Что отрезается¶

Helpdesk Pro отрезает по первому найденному из этого, затем удаляет подпись и телефонный подвал из оставшегося:

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

Кое-что никогда не отрезается:

• Пустой результат. Если после отрезания ничего не осталось и цитата не найдена (тело, состоящее только из подписи), сохраняется полный текст.
• Пересланная почта. Сообщение, пересылающее другое («---------- Forwarded message ---------», «Begin forwarded message:» или тема, начинающаяся с «Fwd:» или «FW:»), сохраняется целиком.

Ответ без нового текста¶

Некоторые ответы ничего не добавляют: человек нажал Reply и Send или переслал уведомление обратно, ничего не написав. Такое сообщение сохраняется как «Replied without adding any text.» с цитатой, свёрнутой под Show quoted text.

Оно тихо присоединяется к переписке: не меняет статус заявки, не считается чьим-либо ответом, и никто не получает о нём уведомление или письмо. В закрытую заявку или заявку, на которую отправитель больше не может ответить, оно ничего не добавляет и не открывает новую (записывается как ignored, no_new_text).

Экран Email¶

Operations → Email (#/setup/email, только для администраторов) говорит, как почта доходит до рабочей области. Сверху: принимается ли входящая почта, приёмник, когда пришло последнее письмо и сколько писем не удалось или удерживается. Всё, что мешает почте приходить, перечислено предложением («No secret set, or it is shorter than 32 characters», «No support address is set») со ссылкой на вкладку настроек, где это исправляется.

• Webhook address: адрес для вставки провайдеру, с секретом, скрытым до Reveal, и Copy. Отдельный секрет подписи следует за ним со своими Reveal и Copy, а также шаги настройки приёмника.
• Mailbox (приёмник imap): сервер и папка, когда ящик читали последний раз и когда прочитают в следующий.
• Replies: адрес ответа, на который просит отвечать ваше письмо, с примером токена, строкой на каждый проект, чей почтовый псевдоним его перехватывает, и напоминанием, что провайдер должен доставлять support+anything@ туда же.
• Try an email: вставьте целое письмо (файл .eml или «Show original» из почтового приложения) и посмотрите, что рабочая область сделала бы с ним: защиту от циклов, кто отправил, в какую заявку оно пойдёт и какие слова сохранит. Оно ничего не сохраняет и никому не пишет.

Журнал входящей почты¶

Каждое полученное письмо получает строку в журнале входящей почты, что бы с ним ни случилось, поэтому у «I emailed you and nothing happened» всегда есть ответ. Администраторы видят его в Operations → Inbound log (#/setup/inbound-log). Счётчик рядом в боковом меню — его неудачные и удерживаемые письма.

Фильтруйте список по состоянию или ищите по отправителю, теме или Message-ID. Открытие письма показывает каждый выполненный шаг обработки (защиту от циклов, отправителя и почему он был удержан или отклонён, как найдена его заявка, что отрезала очистка), сообщение, которым оно стало, каждое сохранённое или пропущенное вложение, заголовки с результатами DMARC, DKIM и SPF и Show original.

• Retry обрабатывает письмо failed снова.
• Process again повторно запускает письмо ignored или rejected после того, как вы исправили настройку, разблокировали отправителя или добавили псевдоним проекта.
• Release пропускает удерживаемый ответ сотрудника, публикуя его от имени этого сотрудника.

Process again и Release могут опубликовать сообщение в заявке, поэтому сначала спрашивают.

Исходная копия, которую хранит журнал, удаляется через privacy.inbound_raw_days дней (по умолчанию 90; 0 хранит её). Сообщение хранит собственный оригинал, пока существует, поэтому Show original в заявке продолжает работать.

Маршруты и инструменты MCP¶

Под /api/v1. Всему, кроме оригинала сообщения, нужно helpdesk-pro.settings.

Задания и уведомления¶

Уведомления inbound_failed и imap_failed в колокольчике только для администраторов, никогда не отправляются по почте и ссылаются на журнал входящей почты.

Настройки¶

На вкладках Email & Notifications → Inbound Email, IMAP Mailbox и Reply Addresses:

Связанные разделы¶

• Исходящая почта
• Устранение неполадок
• CLI
• Расширение