# PHP Newsletter — User Manual

PHP Newsletter is a tool for creating, sending, and analyzing mass email campaigns for your subscribers and business customers.

PHP Newsletter helps you create and send campaigns, manage subscribers, analyze opens and clicks, and place a subscription form on your website without depending on external SaaS platforms.

The application is installed on your own server (self-hosted), giving you more freedom and independence from external newsletter services such as Substack, Mailchimp, Unisender, and SendPulse.

## Benefits of the self-hosted approach

Full data control

Your subscriber database is stored only on your side, without being transferred to third-party platforms.

No subscription fee

You do not pay for the number of subscribers or sent emails.

Flexible configuration

Configure delivery through SMTP, `mail()`, or `sendmail` in the way that works best for you.

No artificial limits

There are no built-in limits on the number of campaigns, subscribers, or emails, except for the capacity of your server and mail infrastructure.

Simple integration

You can place the subscription form on your website using ready-made HTML/JavaScript code from the admin panel.

## Contents

## 1. Who newsletters are useful for

- Creators and bloggers: to build their own audience independently of social media algorithms. They can use newsletters to share exclusive content, expert articles, and announcements of new materials.
- Businesses: to inform customers about new products, promotions, and discounts, encouraging repeat purchases.
- Organizations: to publish regular newsletters, company news, or educational digests.

## 2. System purpose

PHP Newsletter is suitable for:

- news and editorial newsletters;
- marketing campaigns and promotions;
- notifications about new publications, products, or events;
- internal or service emails for registered users.

The system allows you to:

- manage your subscriber database and categories;
- create HTML and plain text emails;
- use personalization through macros;
- schedule email delivery;
- collect statistics on opens and link clicks;
- work entirely on your own infrastructure (self-hosted).

## 3. Server requirements

PHP
8.2 or higher
Database
MySQL 5.6 or higher
Web server
Apache 2+ with `mod_rewrite` or nginx
Mail
`mail()`, SMTP, or sendmail support

### PHP extensions

- MB String
- cURL
- Zip
- Iconv
- GD2

## 4. Installation

1. Extract the archive into the website directory, for example: `/phpnewsletter`.
2. Set `CHMOD 775` permissions for the `.env` file and the `bootstrap/cache`, `public`, and `storage` folders.
3. Open the installer in your browser:
   `http://your_site/phpnewsletter/install/`
4. Follow the installation wizard instructions.

Important: before installation, make sure the server meets the requirements and PHP has write permissions for the listed directories.

## 5. Admin panel sections

Section | Purpose
--- | ---
Templates | Create and edit email templates, add attachments, and start manual sending.
Category | Subscriber categories and mailing segments.
Subscribers | Subscriber database, manual creation, import, export, activation, and deletion.
Macros | Custom macros for template personalization.
Schedule | Schedule campaigns by time and category.
Log | Sending logs, delivery statuses, and report export.
Redirect | Log of link clicks from emails.
SMTP | Manage mail servers and SMTP settings.
Settings | Global settings: delivery, encodings, subscription confirmation, intervals, and limits.
Users | Admin panel users and access roles.
Pages | Utility pages: PHP info, subscription form, and cron task list.

## 6. How the mailing process works

1. You create an email template.
2. You select subscriber categories.
3. You either start sending manually from the admin panel or create a schedule.
4. The system selects active subscribers who have not yet received the email within the current operation.
5. For each email, the subject, body, macros, unsubscribe links, and service headers are generated.
6. After sending, results are written to logs.
7. For HTML emails, the system can track opens and link clicks.

Important: HTML email opens are tracked using a 1x1 pixel. If the email client blocks external images, the open may not appear in the statistics.

## 7. Subscribers and categories

### Manual creation

An administrator can create a subscriber manually by entering a name, email, and categories. Each subscriber has a token used for subscribe and unsubscribe links.

### Import

Supported formats:

- TXT
- CSV
- XLS
- XLSX

Before importing, it is recommended to:

- remove duplicates;
- validate email addresses;
- prepare destination categories in advance;
- make sure the source file encoding is correct.

### Export

Subscriber export is available in text and spreadsheet formats. This is useful for backups, database migration, and external analytics.

### Subscription form

The system includes a built-in public subscription form and routes:

- `/form` — subscription form;
- `/categories` — category list;
- `/add-sub` — add a new subscriber;
- `/unsubscribe/{subscriber}/{token}` — unsubscribe;
- `/subscribe/{subscriber}/{token}` — subscription confirmation.

The subscription form can also be placed on your website. In the admin panel, open the Subscription Form page: it contains a preview of the form and ready-made HTML/JavaScript embed code. Place this code on the desired page of your site; the form will load available categories, submit subscriber data through the public `/add-sub` route, and show a success message or validation errors without redirecting the user to a separate page.

Important when embedding: the ready-made form code uses jQuery and the public routes listed above. Make sure the PHP Newsletter installation is reachable from the page where the form is placed, and that the required subscriber categories are active.

## 8. Templates, macros, and attachments

### Templates

A template contains:

- email name;
- email body;
- sending priority;
- attachments if needed.

### Macros

Macros allow dynamic values to be inserted into a template. In a typical scenario, they are used for:

- subscriber name;
- email;
- service links;
- other personalized data.

### Attachments

Files can be attached to a template. When sending, the system automatically adds the attachments to the email.

## 9. Email delivery methods

Mode | When to use
--- | ---
SMTP | The main and recommended option for production campaigns.
mail() | Suitable only for simple or test scenarios if the server is configured correctly.
sendmail | Used when a working sendmail binary is available on the server and fits your infrastructure.

### Main settings to check

- sender email and sender name;
- content type: HTML or plain text;
- email encoding;
- path to sendmail if this mode is used;
- limit on the number of emails per run;
- delay between emails;
- resend interval for the same subscriber.

## 10. Open and click tracking

### Email opens

For HTML emails, a transparent 1x1 pixel image is added to the message body. When the client loads this image, the system marks the email as opened.

- works only for HTML emails;
- depends on external image loading in the email client;
- does not provide 100% accuracy, but is useful for general analytics.

### Link clicks

Links in emails can pass through an internal redirect route. This makes it possible to save click statistics and see which links recipients click most often.

## 11. Scheduler and cron

The application uses these commands:

- `emails:send` — send scheduled emails;
- `emails:unsent` — retry emails that were not sent successfully.

If cron is not configured: scheduled campaigns will not start automatically, even if they are created in the Schedule section.

## 12. Roles and security

The system includes at least two main roles:

- admin — full access to all sections, including SMTP, settings, and users;
- moderator — access to categories, subscribers, and macros.

### Security recommendations

- use a strong administrator password;
- restrict access to the admin panel by IP if possible;
- keep database backups before updates;
- do not use production SMTP credentials in a test environment;
- periodically check error and sending logs.

## 13. Logs and reports

The system stores:

- email sending history;
- success and error statuses;
- email opens for HTML campaigns;
- link clicks;
- exportable Excel reports.

This helps answer practical questions:

- how many emails were sent successfully;
- how many emails were not sent and why;
- how many emails were opened;
- which links attract more attention.

## 14. Deliverability recommendations

- use SMTP instead of `mail()` for mass campaigns;
- configure SPF, DKIM, and, if possible, DMARC for the sender domain;
- do not send very large email volumes suddenly, without warming up the domain and IP;
- make sure unsubscribe links work correctly;
- do not overload emails with heavy attachments or excessive HTML code;
- send a test campaign to several email providers before a mass launch.

## 15. Project structure

- `app/` — controllers, models, services, DTOs, middleware, helper classes, and console commands;
- `routes/` — web, api, and console routes;
- `resources/views/` — admin templates, subscription forms, and installer;
- `database/migrations/` — database table structure;
- `storage/` — logs, cache, temporary files, and attachments;
- `public/` — public application assets.

## 16. Summary

PHP Newsletter is a solution for those who want to:

- save money on newsletter services;
- keep control over their own database;
- get a flexible and independent email marketing tool.