# PHP Newsletter — Руководство пользователя

PHP Newsletter — инструмент для создания, отправки и анализа массовых рассылок по электронной почте для своих подписчиков и клиентов бизнеса.

PHP Newsletter помогает создавать и отправлять рассылки, управлять подписчиками, анализировать открытия и переходы, а также размещать форму подписки на вашем сайте без зависимости от внешних SaaS-платформ.

Приложение устанавливается на ваш сервер (self-hosted), что даёт больше свободы и независимости от внешних сервисов рассылки, таких как Substack, Mailchimp, Unisender и SendPulse.

## Преимущества self-hosted подхода

Полный контроль данных

Ваша база подписчиков хранится только у вас — без передачи сторонним платформам.

Отсутствие абонентской платы

Вы не платите за количество подписчиков или отправленных писем.

Гибкая настройка

Настраивайте отправку через SMTP, `mail()` или `sendmail` — как удобно именно вам.

Нет ограничений

Нет лимитов на количество рассылок, подписчиков или писем, кроме возможностей вашего сервера и почтовой инфраструктуры.

Простая интеграция

Форму подписки можно разместить на вашем сайте с помощью готового HTML/JavaScript-кода из админ-панели.

## Содержание

## 1. Кому и для чего полезны рассылки

- Авторам и блогерам: для формирования своей аудитории, независимой от алгоритмов соцсетей. Через рассылки они делятся эксклюзивным контентом, экспертными статьями и анонсируют новые материалы.
- Бизнесу: для информирования клиентов о новых продуктах, акциях и скидках, что стимулирует повторные покупки.
- Организациям: для регулярного выпуска информационных бюллетеней, новостей компании или образовательных дайджестов.

## 2. Назначение системы

PHP Newsletter подходит для:

- новостных и редакционных рассылок;
- маркетинговых кампаний и акций;
- уведомлений о новых публикациях, товарах или событиях;
- внутренних или сервисных рассылок для зарегистрированных пользователей.

Система позволяет:

- управлять базой подписчиков и категориями;
- создавать HTML и plain text письма;
- использовать персонализацию через макросы;
- планировать отправки по расписанию;
- собирать статистику открытий и переходов по ссылкам;
- работать полностью на своей инфраструктуре (self-hosted).

## 3. Требования к серверу

PHP
8.2 и выше
База данных
MySQL 5.6 и выше
Веб-сервер
Apache 2+ с `mod_rewrite` или nginx
Почта
Поддержка `mail()`, SMTP или sendmail

### Расширения PHP

- MB String
- cURL
- Zip
- Iconv
- GD2

## 4. Установка

1. Распакуйте архив в каталог сайта, например: `/phpnewsletter`.
2. Установите права доступа `CHMOD 775` для файла `.env` и папок `bootstrap/cache`, `public`, `storage`.
3. Откройте в браузере адрес установщика:
   `http://ваш_сайт/phpnewsletter/install/`
4. Следуйте инструкциям мастера установки.

Важно: перед установкой убедитесь, что сервер соответствует требованиям, а PHP имеет права на запись в указанные каталоги.

## 5. Разделы административной панели

Раздел | Назначение
--- | ---
Templates | Создание и редактирование шаблонов писем, добавление вложений, запуск ручной отправки.
Category | Категории подписчиков и сегментов рассылки.
Subscribers | База подписчиков, ручное добавление, импорт, экспорт, активация и удаление.
Macros | Пользовательские макросы для персонализации шаблонов.
Schedule | Планирование рассылок по времени и категориям.
Log | Логи отправки, просмотр статусов и выгрузка отчётов.
Redirect | Журнал переходов по ссылкам из писем.
SMTP | Управление почтовыми серверами и параметрами SMTP.
Settings | Глобальные настройки: отправка, кодировки, подтверждение подписки, интервалы и ограничения.
Users | Пользователи админ-панели и роли доступа.
Pages | Служебные страницы: PHP info, форма подписки, список cron-задач.

## 6. Как устроен процесс рассылки

1. Вы создаёте шаблон письма.
2. Вы выбираете категории подписчиков.
3. Вы либо запускаете отправку вручную из админки, либо создаёте расписание.
4. Система выбирает активных подписчиков, которым письмо ещё не отправлялось в рамках текущей операции.
5. Для каждого письма формируются тема, тело, макросы, ссылки отписки и служебные заголовки.
6. После отправки записываются результаты в логи.
7. Для HTML-писем система может учитывать открытия и переходы по ссылкам.

Важно: открытие HTML-письма фиксируется через пиксель 1x1. Если почтовый клиент блокирует внешние изображения, открытие может не попасть в статистику.

## 7. Подписчики и категории

### Ручное добавление

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

### Импорт

Поддерживаются форматы:

- TXT
- CSV
- XLS
- XLSX

Перед импортом рекомендуется:

- очистить дубликаты;
- проверить валидность email-адресов;
- заранее определить категории назначения;
- убедиться в корректной кодировке исходного файла.

### Экспорт

Экспорт подписчиков доступен в текстовые и табличные форматы. Это удобно для резервного копирования, переноса базы и внешней аналитики.

### Форма подписки

В системе есть встроенная публичная форма подписки и маршруты:

- `/form` — форма подписки;
- `/categories` — список категорий;
- `/add-sub` — добавление нового подписчика;
- `/unsubscribe/{subscriber}/{token}` — отписка;
- `/subscribe/{subscriber}/{token}` — подтверждение подписки.

Форму подписки также можно разместить на вашем сайте. В админ-панели откройте страницу Форма подписки: там доступен предварительный просмотр формы и готовый HTML/JavaScript-код для вставки. Разместите этот код на нужной странице сайта; форма загрузит доступные категории, отправит данные подписчика через публичный маршрут `/add-sub` и покажет сообщение об успешной подписке или ошибках валидации без перехода пользователя на отдельную страницу.

Важно при размещении: готовый код формы использует jQuery и публичные маршруты, перечисленные выше. Убедитесь, что установка PHP Newsletter доступна со страницы, на которой размещена форма, а нужные категории подписчиков активны.

## 8. Шаблоны, макросы и вложения

### Шаблоны

Шаблон содержит:

- название письма;
- тело письма;
- приоритет отправки;
- при необходимости вложения.

### Макросы

Макросы позволяют подставлять динамические значения в шаблон. В типовом сценарии они используются для:

- имени подписчика;
- email;
- служебных ссылок;
- других персонализированных данных.

### Вложения

К шаблону можно прикреплять файлы. При отправке система автоматически добавляет вложения к письму.

## 9. Способы отправки писем

Режим | Когда использовать
--- | ---
SMTP | Основной и рекомендуемый вариант для боевой рассылки.
mail() | Подходит только для простых или тестовых сценариев, если сервер правильно настроен.
sendmail | Используется, если на сервере есть рабочий бинарник sendmail и он входит в вашу инфраструктуру.

### Основные параметры, которые стоит проверить в настройках

- email и имя отправителя;
- тип контента: HTML или plain text;
- кодировка письма;
- путь к sendmail, если используется этот режим;
- ограничение количества писем за запуск;
- задержка между письмами;
- интервал повторной отправки одному подписчику.

## 10. Отслеживание открытий и переходов

### Открытия писем

Для HTML-писем в тело сообщения добавляется прозрачное изображение 1x1 пиксель. Когда клиент загружает это изображение, система помечает письмо как открытое.

- работает только для HTML-писем;
- зависит от загрузки внешних изображений в почтовом клиенте;
- не даёт 100% точности, но полезно для общей аналитики.

### Переходы по ссылкам

Ссылки в письмах могут проходить через внутренний маршрут редиректа. Это позволяет сохранять статистику кликов и видеть, по каким ссылкам чаще переходят получатели.

## 11. Планировщик и cron

В приложении используются команды:

- `emails:send` — отправка писем по расписанию;
- `emails:unsent` — повторная обработка писем, которые не были отправлены успешно.

Если cron не настроен: запланированные рассылки не будут запускаться автоматически, даже если они созданы в разделе Schedule.

## 12. Роли и безопасность

В системе предусмотрено как минимум две основные роли:

- admin — полный доступ ко всем разделам, включая SMTP, настройки и пользователей;
- moderator — доступ к категориям, подписчикам и макросам.

### Рекомендации по безопасности

- используйте сложный пароль администратора;
- ограничьте доступ к админ-панели по IP, если это возможно;
- держите резервные копии базы данных перед обновлениями;
- не используйте боевые SMTP-учётные данные в тестовой среде;
- периодически проверяйте журналы ошибок и отправки.

## 13. Логи и отчёты

Система хранит:

- историю отправки писем;
- статусы успеха и ошибок;
- открытия писем для HTML-рассылок;
- переходы по ссылкам;
- выгружаемые Excel-отчёты.

Это позволяет отвечать на практические вопросы:

- сколько писем отправлено успешно;
- сколько писем не отправилось и почему;
- сколько писем было открыто;
- какие ссылки привлекают больше внимания.

## 14. Рекомендации по доставляемости

- используйте SMTP, а не `mail()`, для массовых кампаний;
- настройте SPF, DKIM и, по возможности, DMARC для домена отправителя;
- не отправляйте слишком большие объёмы писем резко, без прогрева домена и IP;
- проверяйте, что ссылки отписки работают корректно;
- не перегружайте письмо тяжёлыми вложениями и избыточным HTML-кодом;
- делайте тестовую отправку на несколько почтовых провайдеров перед массовым запуском.

## 15. Структура проекта

- `app/` — контроллеры, модели, сервисы, DTO, middleware, helper-классы и консольные команды;
- `routes/` — web, api и console маршруты;
- `resources/views/` — шаблоны админки, формы подписки и установщик;
- `database/migrations/` — структура таблиц базы данных;
- `storage/` — логи, кэш, временные файлы и вложения;
- `public/` — публичные ресурсы приложения.

## 16. Итог

PHP Newsletter — это решение для тех, кто хочет:

- сэкономить на сервисах рассылок;
- сохранить контроль над своей базой;
- получить гибкий и независимый инструмент email-маркетинга.