Self-hosted email marketing with full source code. Pay once, own forever. Get AcelleMail — $74 →

Get AcelleMail — $74

Build anything. Without forking core.

AcelleMail is a Laravel 11+ email marketing platform with an extensibility surface that goes well beyond callbacks. Sending drivers, payment gateways, AI agents, custom admin pages, page-level UI slots, REST endpoints, lifecycle listeners — every one of them ships as a self-contained plugin under your own namespace. This is the full reference: eleven deep-dives, source-grounded against the canonical code paths in storage/app/plugins/, App\Library\HookManager, and app/Model/Plugin.php.

Start with the foundation ↓ Hello World in 5 min
Extension surfaces
14
Hook patterns
4
Deep-dive pages
11
Reading time
~3h
Source-grounded
100%

How to use this documentation

Read in order if you are starting fresh — every page builds on the one before it. Land on a single page from search if you already know what you need: each deep-dive stands alone with its own breadcrumb, sticky table of contents, and prev/next navigation.

Every claim on every page is traced back to a source file under /Users/luan/apps/acelle/docs/plugin/, docs/sending-server-polymorphism/, docs/payment-order-plan-subscription-saas/, or the live storage/app/plugins/acelle/ai/ implementation. If a claim cannot be cited, it is dropped — not paraphrased.

Reading time, end-to-end: ~3 hours. To ship a real plugin, plan a single afternoon — the Hello World sample takes five minutes to scaffold, and the longest worked example (a sending driver with Postal MTA) is roughly an hour from plugin:init to a passing integration test.

01 — FOUNDATION

Mental model first.

Three pages that get you from “Composer, ServiceProvider, what?” to writing your first Hook::add(...) with confidence. Read these in order. The rest of the docs assume the load flow and the four-pattern hook taxonomy.

getting-started Live

Getting started

Prerequisites, php artisan plugin:init, the eight files the scaffolder writes, the composer.json contract, the activate lifecycle, and the seven most common first-day errors — naming validator, namespace mismatch, missing autoload.psr-4, the register() vs boot() trap.

16 min read Read →
plugin-architecture Live

Plugin architecture

The boot-time load flow: AppServiceProvider::boot → Plugin::autoloadWithoutDbQuery → storage/app/plugins/index.json. register() vs boot() timing. Why inactive plugins still autoload, the four lifecycle states, and the two injection layers.

18 min read Read →
hook-system Live

The Hook system — four patterns

REGISTRY (add/collect), EVENT (on/fire), BEHAVIOR (set/perform), FILTER (modify/filter) — mechanics, real callsites in core, conflict semantics, args-bag convention, six anti-patterns, and a four-question decision tree.

21 min read Read →
02 — BUILDING

Ship a real feature.

Worked examples for the four most-asked patterns: a new sending driver (Postal MTA), a regional payment gateway (Paddle), a custom admin UI surface (the acelle/ai chatbox), and plugin-isolated database tables.

sending-drivers Live

Sending drivers — full plugin pattern

Ship a new MTA backend without forking core. The register_sending_server_driver contract, the driver class + 9 capability markers, validation pipeline, connection blade, webhook controller, identity/warmup. Worked end-to-end against the Postal MTA plugin static review.

19 min read Read →
payment-gateways Live

Payment gateways — Cashier contracts

Pull model, no webhook. The BillingManager registry, four capability interfaces, Paddle as a worked example, the PaymentIntent state machine, and five vendor-boundary discipline rules from the TBANK currency-default lesson.

17 min read Read →
ui-injection Live

UI injection — layouts, sidebar, page slots

Three layout REGISTRY hooks (layout.head.assets, layout.body.before_close, admin.sidebar.groups) plus the page.{controller}.{action}.{slot} contract. The chatbox-bubble pattern from acelle/ai end-to-end, the FILTER variant for redirects, and six anti-patterns.

16 min read Read →
database-models Live

Database & models — plugin-isolated

Migrations under <plugin>/database/migrations/, vendor-prefixed table names, the activate-runs / delete-rolls-back lifecycle, foreign keys to core tables, the $keepData flag, and the fourteen-migration acelle/ai showcase.

13 min read Read →
03 — QUALITY

Make it production-grade.

Translations the indirect way (master file → runtime dump). Per-state lifecycle for register, activate, disable, delete. Pest tests registered through the core phpunit.xml with a fresh activate→test→delete cycle per CI run.

translations Live

Translations

Master file → runtime dump under storage/app/data/plugins/... → admin-editable. The add_translation_file REGISTRY hook, the double-load trap, the eighteen-locale convention, and the translation:upgrade non-destructive merge.

13 min read Read →
lifecycle Live

Plugin lifecycle

Per-state walkthrough: register (5 steps), activate (4 steps), disable (status flip only — autoload + hooks survive), delete (rollback + master-file cleanup). The state diagram, recovery from broken state, and the plugin:* console surface.

13 min read Read →
testing Live

Testing

Plugin testsuite registration in the host phpunit.xml, the PluginTestCase base class with active-row seeding + per-request gate-cache reset, hooks-under-test patterns for REGISTRY / EVENT / BEHAVIOR / FILTER, the activate-test-delete lifecycle integration recipe, and a per-plugin CI matrix.

13 min read Read →
04 — REFERENCE

Read real production code.

The deepest learning happens against a real plugin, not a Hello World. acelle/ai is the canonical complex plugin — eight models, twelve migrations, eighteen locales. Use the showcase to map every concept above onto a single shipping codebase.

showcase Live

Plugin showcase — acelle/ai

The canonical complex plugin walked end-to-end — eight models, fourteen migrations, eighteen locales, every hook surface (six REGISTRY contributions + two EVENT listeners + one BEHAVIOR override), the chatbox UI, the test infrastructure, and a four-step learning recipe.

14 min read Read →
/api Live

REST API reference

Token authentication, the eight resources (Lists, Subscribers, Campaigns, Automations, Sending servers, Customers, Subscriptions, Plans), the six lifecycle webhook events, the three per-recipient tracking pings, and error shapes — the same API plugins use is the same API external clients use.

Endpoint catalog Read →
knowledge.acellemail.com External

Knowledge Base

Operations-side reference: server requirements, supervisor configuration, queue workers, deliverability tuning, DKIM/SPF/DMARC setup, migration playbooks. Read this when the question is “how do I run AcelleMail”, not “how do I extend it”.

Operations hub Open →

Design philosophy

The core declares extension points. Plugins react.
The core never knows your plugin exists.

Inversion of dependency

Core code is never imported by a plugin, and a plugin is never imported by core. The Hook system sits between them as the only contract. Upgrade core, your plugin keeps working — as long as the hook name and signature remain stable, which we version-stamp.

Four patterns, no more

REGISTRY, EVENT, BEHAVIOR, FILTER — the only verbs the Hook system speaks. Conflict semantics are explicit per pattern: REGISTRY merges, EVENT all-fire, FILTER chains, BEHAVIOR is exclusive (two callers throw immediately, no silent override).

Your namespace, forever

Plugins live under MyVendor\MyPlugin\, completely isolated from Acelle\* core. Compose, sell, white-label, fork — your plugin is yours. The Extended License grants commercial redistribution.

Source of truth: the code

Every page in this docs tree links the canonical file path it was traced from. If a doc disagrees with the code, the code wins — file an issue and we update the doc, not the other way around. No legacy copy-paste, no aspirational APIs.

Open the source. Extend the platform.

Full unencrypted PHP. Lifetime updates. The Hook system. Real production plugins to learn from. One-time license — no subscriptions, no per-subscriber fees, no namespace squatting.

Buy Extended License — $199 Back to developer landing

Run your email marketing on
your own server, your own terms

Join thousands of companies that have taken control of their email marketing with full source code, no recurring fees, and unlimited sending. One-time $74 license, lifetime updates.

Get AcelleMail — $74 one-time