cwc-mailer

Система рассылки почты на основе blat, stunnel и juice. Работает по следующему алгоритму:

• получает список адресов из экспорта GMail (файл email.csv);
• загружает шаблон письма (mail.html) в juice для автоматической оптимизации. После этого шага получается временный файл mail.html.juice;
• получает оптимизированный шаблон письма и заменяет все необходимые переменные в нём. На этом шаге получается временный файл, который будет отправлен конкретному получателю. Такой файл называется tmp.html;
• отправляет полученный экземпляр tmp.html с помощью blat и stunnel.

Система однопоточна, с человеко-читаемым выводом в консоль. Пример сообщения об супешной рассылке:

Ready to send [mail.html] to users from [email.csv]
Juice:   OK
Sending...
Sending to <brand@karazin.ua>:    OK
Sending to <sergiy.lilikovych@karazin.ua>:    OK
2 sent, 0 failed.

Установка

Предусловия: chocolatey, nodejs, python3 установлены и настроены. Дальнейшие команды от имени администратора:

choco install blat stunnel -y
npm install juice
blat -install <server addr> <sender's addr> [<try n times> [<port> [<profile> [<username> [<password>]]]]]

Система вызывает juice так, как будто он находится в PATH, поэтому это нужно проверить, так как nodejs в windows по умолчанию не позволяет вызывать модули напрямую. Дайте команду juice из любого места в системе, чтобы убедиться что эта утилита находится в PATH.

Из-за ошибки, наблюдаемой по крайней мере на Windows 8.1 x64, blat не может корректно извлечь пароль из записи профиля, поэтому пароль требуется передавать экземпляру blat в открытом виде. Пароль настраивается в переменной SERVER_PASS скрипта sender/send.py.

В stunnel по-умолчанию уже настроен SMTP для GMail. Достаточно использовать localhost:25 в качестве почтового сервера.

Для работы просмотрщика шаблонов необходимо сделать composer update в каталоге /view/.

Использование

Подготовка к работе заключается в следующем:

• составить шаблон письма. Для этого можно воспользоваться предлагаемой системой шаблонов (см. ниже);
• разместить его в sender/mail.html;
• экспортировать список адресов из GMail и разместить его в файле sender/email.csv;
• запустить sender/run.bat.

Шаблоны

Общая структура

Вы можете подготовить шаблон как угодно, он должен иметь формат html. В файле поддерживаются переменные %USERNAME%, %UID%.

Однако для упрощения работы шаблоны предлагается эксплуатировать систему с помощью системы управления шаблонами SMARTY. Так определён шаблон /layout/classic/. В целях унификации предлагается использовать следующие атрибуты шаблонов:

• index.tpl как необязательную точку входа в пустой шаблон (без блоков);
• docs/ как необязательную директорию с человеко-читаемой документацией к шаблону;
• mail.tpl как обязательную точку входа в готовый шаблон письма;
• style.css как необязательную таблицу стилей;
• screenshot.png как обязательный снимок экрана, демонстрирующий вид итогового документа;
• manifest.json как обязательный файл манифеста вида:

{
  "title": "название шаблона",
  "author": "автор",
  "version": "версия шаблона",
  "dependencies": ["заблон-зависимость 0",...,"заблон-зависимость N"]
}

Наследование шаблонов

В рамках соблюдения принципа DRY шаблоны могут иметь зависимости. После объявления шаблона-зависимости в манифесте, его части могут быть использованы в данном шаблоне.

Шаблон classic не имеет зависимостей и все свои ресурсы определяет самостоятельно. Возможно при разработке последующих шаблонов имеет смысл использовать его style.css.

Для каждого шаблона, для всех его зависимостей и далее по дереву зависимостей устанавливаются переменные <имя шаблона>_path, которые указывают на директорию шаблона относительно view/index.php. Благодаря этому подключение, например, стилевого файла в шаблоне classic выглядит как

{fetch file="$classic_path/style.css"}

Перед загрузкой шаблона система загружает его manifest.json и соответствующие манифесты зависимостей. Если хотя бы один манифест в дереве зависимостей не определён, выполнение завершится ошибкой. Для использования собственных ресурсов нет необходимости дописывать название текущего шаблона в список dependencies манифеста.

Аналогично можно подключать файлы из шаблонов-зависимостей. Например, если тема имеет следующий manifest.json:

{
  "title": "B",
  "author": "author",
  "version": "1.0",
  "dependencies": ["A"]
}

то подключение стилевого файла из шаблона-зависимости A принимает вид:

{fetch file="$A_path/style.css"}

Сборка

Для просмотра шаблонов в сборе предусмотрена соответствующая утилита, расположенная по адресу view. Она подключает SMARTY и для работы ожидает GET параметры layout - название шаблона и template - название точки входа (или любого tpl в директории шаблона). Правильный вызов утилиты (например view/?layout=classic&template=mail) влечет за собой сбор согласно указанной точки входа.

На выходе из утилиты просмотра получается сжатый HTML-файл: без комментариев HTML и CSS, без лишних пробельны символов. Такой файл пригоден для обработки утилитой juice и последующей рассылки.

Аналитика

Для сбора статистики предусмотрен следующий механизм:

• система генерирует UID - уникальный идентификатор письма перед каждой отправкой. UID = md5( e-mail ) и может быть встроен в письмо с помощью переменной %UID%;
• система предоставляет точку сбора статистики, в дистрибутиве расположена в /analitycs/endpoint.php. При вызове этот файл возвращает прозрачный квадратный GIF со стороной 1пкс. После этого он записывает некоторые сведения о пользователях в файл db.php, ставя их в соответствие с UID.

Таким образом, для подключения система съёма статистики в шаблоне достаточно иметь такой код:

<img src="...endpoint.php?uid=%UID%" width="0" height="0">

Записи имеют следующий вид:

e26ed989ef344a9c9d550a354e5d183e	1462436392	66.249.93.185	Mozilla/5.0 (Windows NT 5.1; rv:11.0) Gecko Firefox/11.0 (via ggpht.com GoogleImageProxy)