phil / newsletter-bundle
A site's newsletter for Symfony: lists, double opt-in, campaigns in Markdown in a house layout or sandboxed templates, sending through Symfony Mailer at the pace of sender profiles, one-click unsubscription, a preference center with pause, bounces from IMAP and webhooks, aggregate click counts, mult
Package info
github.com/parler-haut-interagir-librement/newsletter-bundle
Type:symfony-bundle
pkg:composer/phil/newsletter-bundle
Requires
- php: >=8.5
- ext-dom: *
- ext-libxml: *
- ext-mbstring: *
- ext-sodium: *
- doctrine/dbal: ^4.5
- phil/bounce-parser: ^0.1@dev
- phil/email-address: ^0.1@dev
- phil/markup: ^0.2.1@dev
- phil/standard-webhooks: ^0.1@dev
- phil/url: ^0.1.4@dev
- psr/clock: ^1.0
- psr/log: ^3.0
- symfony/config: ^8.2
- symfony/dependency-injection: ^8.2
- symfony/event-dispatcher-contracts: ^3.6
- symfony/http-foundation: ^8.2
- symfony/mailer: ^8.2
- symfony/messenger: ^8.2
- symfony/mime: ^8.2
- symfony/rate-limiter: ^8.2
- symfony/routing: ^8.2
- symfony/scheduler: ^8.2
- symfony/security-core: ^8.2
- symfony/security-csrf: ^8.2
- symfony/service-contracts: ^3.6
- symfony/translation: ^8.2
- symfony/uid: ^8.2
- twig/twig: ^3.30
Requires (Dev)
- doctrine/doctrine-bundle: ^3.3
- doctrine/orm: ^3.7
- phil/automations: ^0.1@dev
- phil/privacy-bundle: ^0.1@dev
- phil/standard-webhooks-bundle: ^0.1@dev
- phpunit/phpunit: ^13.4
- symfony/browser-kit: ^8.2
- symfony/cache: ^8.2
- symfony/clock: ^8.2
- symfony/console: ^8.2
- symfony/css-selector: ^8.2
- symfony/dom-crawler: ^8.2
- symfony/framework-bundle: ^8.2
- symfony/http-client: ^8.2
- symfony/http-kernel: ^8.2
- symfony/remote-event: ^8.2
- symfony/security-bundle: ^8.2
- symfony/twig-bridge: ^8.2
- symfony/twig-bundle: ^8.2
- symfony/yaml: ^8.2
Suggests
- doctrine/orm: To add the newsletter's tables to the schema the ORM generates, with NewsletterSchemaListener
- phil/automations: To offer the triggers and the send and list actions of the newsletter to automations
- phil/privacy-bundle: To answer access and erasure requests for the newsletter's subscribers
- phil/standard-webhooks-bundle: To send the audience events to receivers as signed webhooks
- symfony/console: For the command that reads the bounce mailbox
- symfony/remote-event: To consume the bounce and complaint events of a mail provider's webhook
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-16 01:18:00 UTC
README
A site's newsletter in Symfony: people subscribe, confirm, choose their lists, pause or leave; editors write in Markdown; messages go out through Symfony Mailer at a pace mail providers accept.
phil/newsletter-bundle keeps lists and their subscribers, with a double opt-in when a list asks for one, and sends
campaigns written in Markdown, laid out by the bundle's own layout or by a template an administrator or a member
wrote, which is rendered in Twig's sandbox. Each message carries the one-click unsubscription mail clients show as a
button, and links to a preference center where a subscriber chooses their lists, pauses for a few weeks, or leaves,
saying why if they wish — a reason counted without anything that names them. Messages go out from sender profiles:
an address, one Mailer transport, the hours it sends in, a daily ceiling and a pace per recipient domain. Bounces
come back to an IMAP mailbox read by phil/bounce-parser, or from a provider's webhook through Symfony's RemoteEvent,
and an address that bounced or complained is never mailed again. Clicks are counted in a total per link by default;
counting them per recipient is a campaign's explicit choice, and machines that open links before people are left out
without reading an IP address or a user agent. Nothing tracks the opening of a message.
It is for any Symfony site that writes to its members or readers: a club's news, a shop's announcements, a game's
updates. One application may serve several sites, each with its own audience, sharing templates. With
phil/automations, the bundle offers its triggers and its send and list actions, for welcome sequences and
follow-ups; with phil/privacy-bundle, its part of access and erasure requests; with
phil/standard-webhooks-bundle, signed webhooks of its audience events to other services.
The bundle stores its data in tables of a Doctrine DBAL connection, on PostgreSQL, MySQL, MariaDB or SQLite.
Addresses are validated by phil/email-address, web addresses read by phil/url, Markdown compiled and purified by
phil/markup. Messages, Messenger jobs and webhooks carry identifiers only; the signed links of messages are checked
in constant time. The services keep nothing between requests, so the bundle runs on long-lived workers.
Status
| Part | State |
|---|---|
| Lists, subscribers, memberships, double opt-in, multi-site, external ids | Implemented and tested |
| The subscription form, the confirmation, the one-click unsubscription (RFC 8058), the preference center with pause and an anonymous reason | Implemented and tested |
Campaigns in Markdown, the house layout, templates rendered in Twig\Sandbox\Sandbox, the Markdown editor and its preview |
Implemented and tested |
| Sending through Messenger and Symfony Mailer, sender profiles with one transport each, send windows, daily ceilings, pace per recipient domain | Implemented and tested |
| Click tracking in a total by default or per recipient, machines left out | Implemented and tested |
Bounces from an IMAP mailbox and phil/bounce-parser, VERP, provider webhooks through RemoteEvent, suppression |
Implemented and tested |
The triggers and actions of phil/automations, the privacy module of phil/privacy-bundle, audience webhooks |
Implemented and tested |
| Doctrine DBAL storage, tested on MySQL 8.4 and PostgreSQL 17; a fuzz target for the signed links | Implemented and tested |
| Segments chosen by an audience package | A port, SegmentResolver; the bundle's own reads whole lists |
| An administration of lists, campaigns and templates | Not part of the bundle: the application builds it on the services |
Documentation
| Document | What it covers |
|---|---|
| Installation | Requirements, the recipe, registering, the routes, the tables, the workers. |
| Configuration | Every option, with an example. |
| Subscriptions | Lists, the double opt-in, the pages, leaving, pausing, the reasons, sites. |
| Campaigns | Writing, the Markdown editor, the layouts, sandboxed templates, sending, sender profiles. |
| Tracking | Clicks in a total or per recipient, the machines left out, what is never tracked. |
| Bounces | The IMAP mailbox, VERP, provider webhooks, soft and hard bounces, suppression. |
| Integrations | Automations, privacy requests, audience webhooks, segments. |
| Storage | The tables, what they hold, and what they never hold. |
| Extension points | The services to replace, the ports to implement, and when they are stable. |
| Testing | The bundle's tests, and the servers its integration tests read. |
| Reference | Every class and service of the bundle. |
Quick start
composer require phil/newsletter-bundle
With Symfony Flex, the recipe writes what follows. Without it:
// config/bundles.php Phil\NewsletterBundle\PhilNewsletterBundle::class => ['all' => true],
# config/packages/phil_newsletter.yaml phil_newsletter: secret: '%env(NEWSLETTER_SECRET)%' sites: default: { base_url: 'https://example.com' } profiles: default: { from: 'news@example.com', from_name: 'Example' }
# config/routes/phil_newsletter.yaml phil_newsletter: resource: '@PhilNewsletterBundle/config/routes.php' prefix: /newsletter
Requirements
PHP 8.5 or later, Symfony 8.2 or later, Twig 3.30 or later and Doctrine DBAL 4.5 or later.
Contributing
Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.
License
MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.