Inherent.Automation

Email automation plugin for OctoberCMS (from v3 onward). Manages subscriber lists, double opt-in, multi-step email sequences, open/click tracking, and unsubscribe (RFC 8058 compliant).

Replace email automation like system.io, mailerlite, brevo, etc...

Requirements

• OctoberCMS v3
• PHP 8.2+
• A configured mail driver (SMTP, Mailgun, SES…)

Installation

1. After installation from the marketplace : Add the scheduler entry to your crontab. Use the full PHP binary path — cron does not inherit your shell PATH: -e then add the line

   * * * * * "/path/to/your/root/project/php" /path/to/artisan schedule:run >> /dev/null 2>&1

The scheduler runs automation:process every minute to dispatch queued emails.

Backend user guide

Subscriber lists

Automation > Lists

A list groups subscribers under a name and optional sender identity. Each list has a unique code (auto-generated from the name, editable).

Mark one list as default so the subscribe form falls back to it when no explicit list is configured.

Subscribers

Automation > Subscribers

A subscriber is identified by email address. The subscriber record carries a global status that acts as a high-water mark:

Subscription status is tracked per list, not globally. The same subscriber can be confirmed on list A and pending on list B — both the global status and the per-list pivot status coexist independently. The Lists tab on the subscriber form shows the pivot status, subscription date, and unsubscription date for each list.

Adding a list from the backend (via the Add button) confirms the subscription immediately, bypassing double opt-in.

The backend form page shows all list memberships and the full email history for that subscriber.

Email templates

Automation > Email Templates

Reusable email bodies written in HTML + Twig. Templates define subject, HTML body, and optional sender overrides (from name, from email).

Available Twig variables:

The layout file (views/mail/email_layout.htm) wraps all rendered bodies. Edit it to change the global email frame. It receives the same variables plus {{ body }}.

Automations

Automation > Automations

An automation is a sequence of steps triggered by an event.

Trigger types:

Steps

Each automation has ordered steps. A step = one email sent after a delay (in days).

Priority rule: inline step fields override the template, which overrides the list defaults, which override mail.from.

When a trigger fires, the engine enqueues one item per step, each scheduled at trigger_time + cumulative delay.

Queue

Automation > Queue

Read-only view of all queue items. Useful for debugging delivery issues.

Reports

Automation > Reports

Global index — Total confirmed subscribers, new (30 days), emails sent (30 days), open rate (30 days). Tables for all automations and all lists with key stats.

Per-automation (/reports/automation/{id}) — Total sent / opened / clicked / pending. Per-step breakdown with open rate and click rate. 50 most recent send events.

Per-list (/reports/list/{id}) — Confirmed subscriber count, new today, emails sent and open rate across all automations linked to this list. Table of linked automations. 20 most recent confirmed subscribers.

Per-subscriber (/reports/subscriber/{id}) — Subscription history across all lists with statuses and timestamps. Full email history: automation, step, subject, sent time, opened time, click count, status.

Frontend component

automationSubscribeForm

Attach to any CMS page or layout to render a subscription form with double opt-in.

[automationSubscribeForm]
listId = 1
allowListChoice = 0
successMessage = "Thank you! Check your email to confirm."

selectableLists is only used when allowListChoice is enabled. It lets you restrict the choice to a curated subset without exposing every list.

The form submits via AJAX. On success it replaces the form with the success message. Validation errors appear inline.

The default template (components/subscribeform/default.htm) is unstyled HTML. Override it from your theme. The updatable inner content lives in components/subscribeform/_form.htm — override that partial when you only need to restyle the form and success state.

Developer guide

Architecture overview

── subscribe_to_list trigger ──────────────────────────────────────────────────

SubscribeForm (component)
    └── SubscriberManager::signup()
            sends confirmation email

TrackingHandler::confirmSubscription()
    └── SubscriberManager::confirm()
            updates pivot status → fires inherent.automation.subscriber.confirmed

Event: inherent.automation.subscriber.confirmed
    └── AutomationEngine::onSubscriberConfirmed()
            enqueues steps → AutomationQueue

── custom_event trigger ───────────────────────────────────────────────────────

Any plugin
    └── AutomationEngine::trigger('event-name', $subscriber)
            looks up active automations by event name
            enqueues steps → AutomationQueue (subscriber_list_id = null)

── dispatch (both paths) ──────────────────────────────────────────────────────

Scheduler (every minute)
    └── php artisan automation:process
            └── AutomationWorker::process()
                    dispatches due queue items
                    records AutomationLog with tracking code

Public routes

Events

\Event::listen('inherent.automation.subscriber.confirmed', function ($subscriber, $list) {
    // $list is always a SubscriberList instance here
});

\Event::listen('inherent.automation.subscriber.unsubscribed', function ($subscriber, $list) {
    // $list may be null if the automation had no list context (custom_event trigger)
});

SubscriberManager API

use Inherent\Automation\Classes\SubscriberManager;

// Sign up from a form — creates subscriber + pivot, sends confirmation email
$subscriber = SubscriberManager::signup($email, [1, 3], [
    'first_name' => 'Marie',
    'last_name'  => 'Dupont',
], $request->ip());

// Sign up from a RainLab User object
$subscriber = SubscriberManager::signupFromUser($user, [1]);

// Confirm directly — bypasses double opt-in (backend/admin action)
SubscriberManager::confirmDirect($subscriber, $list);

// Unsubscribe by tracking code (called by the unsubscribe route)
SubscriberManager::unsubscribeByTrackingCode($trackingCode);

signup() is idempotent: calling it twice with the same email only sends a new confirmation if the subscriber had previously unsubscribed.

Custom event trigger

Fire a named automation from any plugin:

use Inherent\Automation\Classes\AutomationEngine;

// Pass a Subscriber instance
AutomationEngine::trigger('order.placed', $subscriber);

// Pass an email string — throws \InvalidArgumentException if not found in DB
AutomationEngine::trigger('order.placed', 'customer@example.com');

In the backend, create an automation with trigger "When a custom event is triggered" and set the event name to order.placed. All active automations matching that slug will enqueue their steps for the subscriber.

The subscriber must already exist in the database. The method does not auto-create subscribers — the caller controls consent and opt-in.

Unsubscribe behaviour — with no list context, clicking the unsubscribe link cancels all pending queue items for that subscriber in the triggered automation. The subscriber's global status and other list memberships are unaffected.

Example (MelonCart / Mall)

// After a completed order
$subscriber = Subscriber::where('email', $order->customer_email)->first();

if ($subscriber) {
    AutomationEngine::trigger('order.placed', $subscriber);
}

// After a loyalty milestone
if ($customer->completedOrdersCount() >= 5) {
    AutomationEngine::trigger('loyalty.vip', $subscriber);
}

RainLab.User integration

When RainLab.User is installed, set rainlab_user_default_lists in the plugin config to auto-subscribe new registrations:

// config/config.php
    'rainlab_user_default_lists' => [1, 2],

New users are signed up with a confirmation email sent to those list IDs.

Confirmation redirect

After a subscriber clicks the confirmation link, the plugin redirects to the URL defined by confirm_redirect in config/inherent/automation.php:

// config/inherent/automation.php
return [
    'confirm_redirect' => env('AUTOMATION_CONFIRM_REDIRECT', '/email-confirmation'),
];

Set AUTOMATION_CONFIRM_REDIRECT in your .env to override without touching the config file:

AUTOMATION_CONFIRM_REDIRECT=/merci-de-votre-inscription

Defaults to /email-confirmation if the variable is absent.

Running automations manually

php artisan automation:process

Picks up all queue items with scheduled_at <= now() and status = pending, processed in batches of 50.

Extending with new trigger types

1. Add the key to Automation::getTriggerTypeOptions().
2. Call AutomationEngine::enqueueForSubscriber($automation, $subscriber, $list) from wherever the trigger fires.

\Event::listen('your.custom.event', function ($user) {
    $subscriber = Subscriber::where('email', $user->email)->first();
    if (!$subscriber) return;

    Automation::active()
        ->where('trigger_type', 'your_trigger')
        ->with('steps')
        ->get()
        ->each(fn ($automation) => AutomationEngine::enqueueForSubscriber($automation, $subscriber));
});

Responsiv.Campaign integration

When the Responsiv Campaign plugin is installed, Inherent.Automation registers its subscriber lists as recipient groups inside Campaign. No configuration required — the integration activates automatically on boot. Set the environment variable AUTOMATION_CAMPAIGN_INTEGRATION=true to enable this automatic integration. Per default, it is set to false by config.

What it does

Each confirmed-subscriber list appears in Campaign's message composer under a group named Automation : <list name>. Marketers can target these segments directly when sending a one-time newsletter or bulk campaign, without duplicating subscribers between the two plugins.

Only subscribers with a confirmed status on the list are exposed.

How it works

The plugin listens to two Campaign events:

Groups are keyed automation_list_{id} to avoid collisions with other Campaign recipient sources.

Enabling / disabling

The integration is off by default when Campaign is installed. Enable/Disable it via .env:

#AUTOMATION_CAMPAIGN_INTEGRATION=true
AUTOMATION_CAMPAIGN_INTEGRATION=false

Or directly in config/inherent/automation.php:

'campaign_integration' => false,

Requirements

• responsiv/campaign installed and active

Permissions

Changelog

1.0.4

• automationSubscribeForm: new selectableLists property (type set). When allowListChoice is on, only the selected lists are shown to the visitor. Leave empty to keep the previous behaviour (all lists).
• automationSubscribeForm: fixed confirmation message not appearing after form submission. The AJAX update now returns the rendered inner partial directly from the handler, avoiding the onRun / re-render conflict that reset subscribed to false.
• Responsiv.Campaign integration: when Campaign is installed, Automation subscriber lists are automatically registered as recipient groups in Campaign's message composer (confirmed subscribers only). Disable via AUTOMATION_CAMPAIGN_INTEGRATION=false or campaign_integration in config.

1.0.3

• New trigger type custom_event: fire automations from any plugin via AutomationEngine::trigger('event-name', $subscriber).
• Fixed unsubscribeByTrackingCode() for automations with no list context (subscriber_list_id = null): pending queue items are now cancelled per-automation instead of silently ignored.
• Reports: per-automation report (step breakdown, open/click rates), per-list report (linked automations, recent subscribers), per-subscriber report (full history with subjects and click counts). Fixed open rate query on list report (was using whereJsonContains on a non-existent JSON field).
• Subscriber form: Lists tab now shows per-list pivot status, subscription date, and unsubscription date.