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

Contents

1. Who newsletters are useful for
2. System purpose
3. Server requirements
4. Installation
5. Admin panel sections
6. How the mailing process works
7. Subscribers and categories
8. Templates, macros, and attachments
9. Email delivery methods
10. Open and click tracking
11. Scheduler and cron
12. Roles and security
13. Logs and reports
14. Deliverability recommendations
15. Project structure
16. Summary

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 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.

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.

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.

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.

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.