Перейти к содержанию

Установка

Эта страница приводит Mailroom к работе: плагин, его база данных, обработчик и права.

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

  • Grav 2.1.0 или новее с Admin Next, плагином API (1.0.31 или новее) и плагином Email (5.1.0 или новее).
  • Плагин Email настроен и отправляет письма. Проверьте его командой bin/plugin email test-email --to=you@example.com.
  • PHP 8.3 или новее с PDO и драйвером вашей базы данных (pdo_sqlite для значения по умолчанию).
  • Ваша лицензия Mailroom добавлена в License Manager.

Установка плагина

Установите через GPM, как любой другой плагин:

bin/gpm install mailroom

Его также можно установить из Plugins в Admin Next. После включения Mailroom добавляет пункт Mailroom в боковое меню Admin Next для всех, у кого есть mailroom.view (и для суперпользователей), а также собственные команды под bin/plugin mailroom.

Чтобы включить его вручную, задайте enabled: true в user/config/plugins/mailroom.yaml.

База данных

Mailroom хранит подписчиков, кампании и очередь заданий в собственной базе данных. Каждая создаваемая им таблица начинается с mailroom_.

SQLite (по умолчанию)

Настраивать нечего. При первом чтении базы данных Mailroom создаёт её в user-data://mailroom/mailroom.sqlite (то есть user/data/mailroom/mailroom.sqlite) и применяет миграции. Папка получает .htaccess, запрещающий всё.

Предупреждение

Файл .htaccess защищает базу данных только на Apache. Стандартные правила сервера Grav не мешают скачать файл .sqlite из user/, а nginx и Caddy игнорируют .htaccess. На таких серверах запретите папку сами. Для nginx:

location ^~ /user/data/ { deny all; }

Чтобы хранить файл в другом месте, задайте SQLite File (database.sqlite.path) на вкладке Advanced настроек Mailroom как потоковый путь (user-data://...) или абсолютный путь.

MySQL, MariaDB или PostgreSQL

  1. Создайте пустую базу данных и пользователя, который может создавать в ней таблицы.
  2. На вкладке Advanced настроек Mailroom задайте Database (database.type) как MySQL or MariaDB или PostgreSQL и заполните хост, порт, имя базы данных, имя пользователя и пароль в разделе для этого сервера. MySQL может использовать сокет Unix вместо хоста и порта; у PostgreSQL есть SSL Mode.
  3. Сохраните, затем запустите:
bin/plugin mailroom migrate

Примечание

Смена Database направляет Mailroom на другую, пустую базу данных. Ничего не копируется.

Когда применяются изменения таблиц

Update the Tables (database.auto_migrate) решает, когда применяются изменения схемы новой версии:

Значение Название Что происходит
sqlite (по умолчанию) Само на SQLite, иначе из командной строки SQLite применяет ожидающие миграции при первом использовании после обновления. Серверная база данных ждёт bin/plugin mailroom migrate.
auto Само, в любой базе данных Каждая база данных применяет ожидающие миграции при первом использовании.
manual Только из командной строки Ничего не применяется, пока вы не запустите bin/plugin mailroom migrate. 
bin/plugin mailroom migrate --status   # список ожидающих миграций
bin/plugin mailroom migrate            # применить

Обработчик и каждая команда, читающая базу данных, отказываются работать, пока ждут миграции, и говорят сначала запустить migrate. Публичные страницы (подписка, подтверждение, отписка, предпочтения, просмотр в браузере и webhook провайдеров) тем временем отвечают 503 с Retry-After: 300 страницей «попробуйте снова через несколько минут» вместо ошибки; пиксель открытия всё равно отдаёт своё изображение. Почтовый провайдер повторяет webhook, получивший 503, поэтому ничего из того, что он сообщает, не теряется.

Настройка cron

Всё, что отправляет Mailroom, — задание в его очереди: кампании, письма подтверждения, шаги автоматизаций, импорт и пересчёт сегментов. Задания, поставленные веб-запросом (письмо подтверждения после подписки), выполняются сразу после его ответа, но кампаниям, автоматизациям, повторным попыткам и всему запланированному нужен обработчик, который планировщик Grav запускает каждую минуту. Добавьте планировщик в crontab со строкой PATH:

PATH=/usr/local/bin:/usr/bin:/bin
* * * * * cd /path/to/site && php bin/grav scheduler >> /dev/null 2>&1

Укажите в строке PATH папку, в которой лежит ваш бинарный файл PHP. bin/plugin mailroom status печатает точную строку планировщика для вашего сайта.

Задания и cron объясняют очередь, разгрузку после запроса и строку PATH.

Доступ для команды

Администраторам нужен api.access для доступа к Admin Next, а также собственные права Mailroom:

Право Название Что покрывает
mailroom.view View Mailroom Чтение подписчиков, кампаний, отчётов и настроек
mailroom.manage Manage Mailroom Запись: кампании, списки, шаблоны, импорт, исключения, настройки, ручная отписка, удаление данных
mailroom.send Send Mailroom Campaigns Запуск, продолжение и тестовая отправка кампании, а также отправка новичкам и повтор неудачных отправок

Отправка отделена, потому что кампанию нельзя вернуть после отправки. mailroom.send проверяется вместе с mailroom.manage, никогда вместо неё, поэтому отправителю нужны оба. У суперпользователей (api.super) есть всё.

Полезное разделение, настроенное в Accounts в Admin Next:

Группа Права
newsletter-writers api.access, mailroom.view, mailroom.manage
newsletter-senders api.access, mailroom.view, mailroom.manage, mailroom.send

Тот, у кого нет mailroom.manage, видит каждый экран только для чтения со строкой «Changing anything here needs the Manage Mailroom permission.»

Первые проверки

  1. Откройте Admin Next как администратор. В боковом меню появляется Mailroom, и открывается страница Mailroom по /admin/plugin/mailroom.
  2. Запустите bin/plugin mailroom status. Она показывает базу данных, схему, базовый маршрут, может ли плагин Email отправлять письма, адрес From, адрес сайта, очередь и когда обработчик запускался последний раз, и говорит, что исправить.
  3. Запустите bin/plugin mailroom work. Он выполняет один проход обработчика и говорит, что сделал.

Чтобы осмотреться с данными, bin/plugin mailroom seed наполняет пустой Mailroom трёхмесячной рассылкой небольшого проекта. Ничего не отправляется, а seed --purge удаляет ровно то, что добавил. См. CLI.