Simple Newsletter turns your Joomla site into a self-hosted mailing list: a subscribe form on the front end, double opt-in confirmation, e-mail templates with placeholders, and batched sending that survives a PHP timeout. This page is the complete manual.
Contents
- What gets installed
- Requirements
- Installation
- Quick start
- Options reference
- Subscribers
- Templates and placeholders
- Starter layouts
- Sending a newsletter
- Send history and resuming
- The subscribe module
- A subscription page
- Unsubscribing
- Permissions
- Database tables
- Troubleshooting
- Updating and uninstalling
1. What gets installed
The package pkg_simplenewsletter.zip installs two extensions:
- Simple Newsletter (
com_simplenewsletter) — the component, with its administrator screens and the front-end endpoints that handle confirmation and unsubscribe links. - Simple Newsletter Subscribe (
mod_simplenewsletter) — the site module holding the subscribe form.
It also creates four database tables and one example template called Default newsletter, so there is something to look at immediately.
In the administrator you will find Components → Simple Newsletter with four screens: Subscribers, Templates, Send Newsletter and Send History.
2. Requirements
- Joomla 5.1 or newer, including Joomla 6
- PHP 8.1 or newer
- MySQL or MariaDB
- A working mail setup in Global Configuration → Server → Mail
No cron job and no external service are needed. If your contact form already delivers mail, so will this.
3. Installation
- Log in to the administrator as a Super User.
- System → Install → Extensions.
- On the Upload Package File tab, drop in
pkg_simplenewsletter.zip. - Wait for the success message.
If the install fails, the usual cause is an upload limit rather than the package: check upload_max_filesize and post_max_size in your PHP configuration, or use the Install from Folder tab after uploading the ZIP by FTP.
4. Quick start
Five minutes, in this order:
- Check the sender. Components → Simple Newsletter → Options → Sender. The default, Use Joomla Global Configuration, is usually correct.
- Publish the module. Content → Site Modules → New → Simple Newsletter Subscribe. Pick a position and publish.
- Subscribe yourself from the front end and click the link in the confirmation e-mail. This proves the whole opt-in chain works before you invite anyone.
- Look at a template. Templates → open Default newsletter, or create one and press Start from a layout.
- Send a test. Send Newsletter → pick the template → put your address in the test field → Send test. When that looks right, press Send Now.
5. Options reference
Components → Simple Newsletter → Options.
Sender
| Sender settings | Either Use Joomla Global Configuration (default) or Enter settings manually. The three fields below appear only in manual mode. |
| From name | The name recipients see. Left empty, the Global Configuration value is used. |
| From email | The address messages are sent from. Left empty, the Global Configuration value is used. It must be an address your SMTP account is allowed to send from. |
| Reply-to | Where replies go. Left empty, replies go to the From address. |
Whatever you choose here, the Send screen shows the address that will actually be used and where it came from, so there is no guessing.
Sending
| Emails per batch | Default 25. How many messages are sent per request. Lower it if your server times out; raise it on a fast host to finish sooner. |
| Add List-Unsubscribe header | Default Yes. Adds the Unsubscribe control that Gmail and Outlook show next to your name. Leave it on: readers who can unsubscribe in one click do that instead of reporting spam, which protects your domain. |
| Keep recipient detail for (days) | Default 30. Each send stores one row per recipient so you can see which addresses failed. Rows older than this are removed automatically when a send finishes. The summary line in the history is always kept. Set 0 to keep everything forever. |
| Pause between emails (ms) | Default 0. Waits this long after each message. Use it when your host enforces an hourly sending limit — 200–500 ms is a common setting on shared hosting. |
Opt-in
| Ask for name | Whether the subscription form on a menu item shows a name field. The module has its own setting for this. |
| Confirmation subject | Subject of the confirmation e-mail. Left empty, a sensible default including your site name is used. Placeholders work here. |
| Confirmation email | Body of the confirmation e-mail, edited in your normal Joomla editor. It must contain {confirm_link}, or nobody can confirm. Left empty, a plain built-in text is used. |
| Confirmation link validity (days) | Default 7. After this, clicking the link issues a fresh one instead of confirming, and the visitor is told to check their inbox again. Set 0 for links that never expire. |
| Landing page | The menu item visitors land on after confirming or unsubscribing. Left empty, they land on the site root. A short "thank you" article makes a better landing page than the front page. |
6. Subscribers
Every address has one of four states:
| Pending | Signed up but has not clicked the confirmation link. Receives nothing. |
| Confirmed | Clicked the link. Only these receive newsletters. |
| Unsubscribed | Opted out. The row is deliberately kept rather than deleted, so the same address cannot quietly be added again by a later sign-up without a fresh confirmation. |
| Trashed | Hidden from the default list. Use Delete to remove permanently. |
From the toolbar you can:
- New — add an address by hand. Setting it straight to Confirmed skips the opt-in e-mail, which is what you want when importing a list people already agreed to.
- Actions — mark the selected rows Confirmed, Pending or Unsubscribed, resend the confirmation e-mail, or delete.
- Export CSV — downloads the list as currently filtered and searched, with id, name, e-mail, state, sign-up date and confirmation date.
Search accepts a name or an e-mail address, or id:12 to jump to a specific row.
7. Templates and placeholders
A template is a reusable newsletter: a title (for your eyes only), a subject line, and an HTML body edited in your normal Joomla editor. Unpublished templates do not appear in the Send screen.
These placeholders work in both the subject and the body, and are replaced for each recipient at the moment the message is sent:
{name} |
The subscriber's name. Empty if they never gave one — so write "Hello {name}," rather than relying on it. |
{email} |
The subscriber's e-mail address. |
{unsubscribe_link} |
That subscriber's personal opt-out URL. Every newsletter should contain this. All six supplied layouts already do. |
{confirm_link} |
The opt-in URL. Only meaningful in the confirmation e-mail in Options. |
{sitename} |
Site name from Global Configuration. |
{siteurl} |
Your site's root URL. |
{date} |
Today's date, formatted for the site language. |
The eye icon in the Templates list opens a preview rendered with sample data, so you can see the result without sending anything.
Two things worth knowing about e-mail HTML: mail clients ignore most modern CSS, which is why the supplied layouts use tables and inline styles; and images must be referenced by absolute URL, because a recipient's mail client cannot resolve a relative path on your site.
8. Starter layouts
In the template editor, Start from a layout opens a picker with six designs. Select one to preview it on the right, then Use this to insert it. If the body already has content you are asked to confirm first, and the subject is filled in only when you have not written one yourself.
| Simple letter | One column, no images. Reads like a personal note. |
| Hero and call to action | Dark banner, headline, short body, one prominent button. |
| Two-column roundup | Dated masthead with two story cards side by side. |
| Product grid | Four tiles with price and button. |
| Event invitation | Date badge, details block, RSVP button. |
| Minimal, text only | Serif type, hairline rules, no boxes. Tends to avoid the Promotions tab. |
The layouts are ordinary HTML files in administrator/components/com_simplenewsletter/presets/. To add your own, drop in my-layout.html and add an entry to presets.json in the same folder.
9. Sending a newsletter
Components → Simple Newsletter → Send Newsletter.
- Choose a template. The preview pane on the right updates as you switch.
- Adjust the subject if you want something different from the template's own.
- Check the summary: how many confirmed recipients there are, the batch size, and the From address with a note saying whether it comes from Global Configuration or from this component's options.
- Send a test first. Put an address in the test field and press Send test. Placeholders are rendered, and if that address is already a subscriber its real token is used, so the unsubscribe link in the test is live.
- Press Send Now and confirm.
What happens then: a job record is created and one queue row is written per confirmed subscriber. Messages go out in batches, and the progress bar counts sent and failed as it goes. Each recipient's result is stored individually, so one rejected address does not abort the run.
Sending runs in this browser tab. Leaving the page stops it — but nothing is lost, see the next section. Cancel stops after the current batch; recipients not yet reached are simply left unsent.
10. Send history and resuming
Send History lists every newsletter you have sent, with its status and its sent / failed / total counts. Opening one shows each recipient, and for every failure the reason your mail server gave — an invalid address, a rejected sender, a full mailbox. Filter by Failed to see only the problems.
If a send was interrupted, the job stays in Running with recipients still queued. Both the Send screen and the history list then offer Resume, which picks up exactly where it stopped. Because state is tracked per recipient, nobody receives the message twice.
Housekeeping: per-recipient rows are removed automatically once a finished job passes the retention window set in Options, and Clean up detail rows in the toolbar does it on demand. Delete removes selected jobs and their rows entirely.
11. The subscribe module
Content → Site Modules → New → Simple Newsletter Subscribe.
| Intro text | A line above the form. HTML allowed. |
| Show name field | Whether to ask for a name as well as an address. |
| Name required | Only shown when the name field is on. Asking for less gets you more sign-ups. |
| Button text | Defaults to "Subscribe". |
| Button CSS class | Defaults to btn btn-primary. Put your template's own button class here to match the rest of the site. |
| Form layout | Stacked for sidebars, Inline for a footer strip. |
| Privacy note | Small print under the button — a good place for a link to your privacy policy. |
The form carries a hidden honeypot field that a human never fills in; submissions that fill it are silently accepted and discarded, so bots get no feedback. It also carries a Joomla CSRF token, which is worth knowing if you cache aggressively — see Troubleshooting.
12. A subscription page
If you prefer a dedicated page to a module, create a menu item of type Simple Newsletter → Subscription Form. It renders the same form full width. Whether the name field appears is controlled by Ask for name in the component Options.
This also makes a good Landing page target for confirm and unsubscribe links.
13. Unsubscribing
Every layout's footer contains {unsubscribe_link}, which resolves to a URL unique to that subscriber. Clicking it sets the row to Unsubscribed and shows a confirmation message on your landing page. Clicking it twice is harmless.
With Add List-Unsubscribe header switched on, messages also carry the RFC 8058 headers that make Gmail, Outlook and Apple Mail display their own Unsubscribe control next to the sender name. That control posts to a dedicated endpoint which answers immediately without redirecting, as the standard requires.
One consequence worth knowing: because the unsubscribe URL is a plain link, a security scanner that follows links in e-mail can occasionally unsubscribe somebody who never clicked. It is rare. If it matters to you, point the Landing page at an article that explains what happened and offers a link back to the subscribe form.
14. Permissions
Options → Permissions exposes the usual Joomla actions plus one of our own:
| Access Administration Interface | See the component at all. |
| Create / Edit / Delete / Edit State | Manage subscribers and templates. |
| Send Newsletter | Separate from editing. An editor can prepare templates without being able to send to the whole list. |
15. Database tables
#__simplenewsletter_subscribers | One row per address, with state, token and timestamps. |
#__simplenewsletter_templates | Your newsletters. |
#__simplenewsletter_jobs | One row per send, with counts. Small, kept indefinitely. |
#__simplenewsletter_queue | One row per recipient per send, pruned by the retention setting. |
#__ is Joomla's table prefix token; on your site it becomes whatever prefix you chose at install.
16. Troubleshooting
Nothing arrives, and no error is shown
Check Global Configuration → Server → Mail → Send Mail. If it is off, Joomla sends nothing and reports no error. The Send screen warns you about this, but it is the first thing to check.
Messages are sent but land in spam, or fail with a rejection
Almost always the From address. If Joomla is sending through SMTP, most providers only allow the account's own address in the From field — sending as
Beyond that, deliverability is a domain matter rather than a software one: publish SPF and DKIM records for the domain you send from, and prefer authenticated SMTP over PHP mail.
The send stops partway through
A PHP timeout, or the tab was closed. Open Send Newsletter or Send History and press Resume. To stop it happening again, lower Emails per batch.
"Invalid token" when someone subscribes
The page holding the form was served from cache with a stale CSRF token. Exclude pages carrying the module from your page cache, or turn off Joomla's System - Page Cache plugin for them. This affects every Joomla front-end form, not just this one.
The confirmation e-mail arrives with {confirm_link} shown literally
The custom confirmation body in Options lost the placeholder, or an editor escaped it. Clear the field to fall back to the built-in text, then re-add your wording around a working {confirm_link}.
Confirmation links point at the wrong host
Links are built from your site's own root URL. If the site redirects between the bare domain and www, set the canonical form in Global Configuration so the links match it from the start.
An admin screen shows an error that persists after a fix
Joomla renders error pages with an HTTP 404 status, which browsers and server-side caches happily remember for that exact URL. Add &x=1 to the address to force a fresh request; if that works, the fix is fine and only the cached page was stale.
17. Updating and uninstalling
Updates arrive through System → Update → Extensions like any other Joomla extension — no download key and no account. You can also install a newer package over the old one; Joomla treats it as an upgrade and your subscribers, templates and history are untouched.
To uninstall, remove the Simple Newsletter package from System → Manage → Extensions. That removes the component and the module together.
Uninstalling drops all four tables, including your subscriber list. Export your subscribers to CSV first if there is any chance you will want them back.
