juice+blat mailing system for ~1000 subscribers
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
analitycs
layout
sender
view
.gitignore
LICENSE
README.MD

README.MD

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)