A brand-new MTA backend. Shipped as a plugin. Without forking core.

Why ship a driver as a plugin

The contract — what a plugin ships

The full file tree of a sending-driver plugin:

storage/app/plugins/vendor/name/
├── composer.json          // PSR-4 & Laravel provider hook
├── icon.svg               // driver logo for the picker page
├── routes.php              // picker page route, served by routes.php
├── src/
│   ├── ServiceProvider.php // the hook: name & namespace lifecycle
│   └── Driver.php          // the driver class
├── resources/
│   ├── views/
│   │   └── connection_tab.blade.php // the connection-tab form fields
│   └── lang/
│       └── en.php          // labels & help text

ServiceProvider — the boot pattern

The full skeleton service provider for a sending-driver plugin (paraphrased from the Postal plugin):

<?php

namespace MyVendor\Sending;

use Acelle\Library\Support\ServiceProvider as Base;

class MySendingServiceProvider extends Base
{
    const PLUGIN_NAME = 'myvendor/sending'; // MUST match composer.json:name

    public function register(): void
    {
        // Translation file registration - see developers/translations for
        // the full contract. MUST be in register(), never in boot(), or the
        // host application can't find the labels during component build.
        Hook::add('add_translation_file', function() {
            return [
                'plugin_name'   => self::PLUGIN_NAME,
                'type'          => 'translation',
                'translation_folder' => __DIR__.'/../resources/lang/en/',
                'translation_prefix' => 'myvendor',
                'master_translation_file' => realpath(__DIR__.'/../resources/lang/en/messages.php'),
            ];
        });
    }

    public function boot(): void
    {
        // (1) View namespace - plugin's own views.
        // Used in Connection tab as 'myvendor::fields'
        $this->loadViewsFrom(__DIR__.'/../resources/views', 'myvendor');

        // (2) The single REGISTRY hook that the SendingServiceProvider
        // listens for. This registers the driver into the sending core.
        // It should return an array if the driver is ready.
        Hook::add('register_sending_driver_provider', function() {
            return [
                'type'        => 'myvendor-driver-type',
                'name'        => 'MyVendor SMTP',
                'driver_class' => 'MyVendor\Sending\Driver',
                'config_keys'  => ['api_key', 'my_region'], // JSON config column
                'description' => 'Send via MyVendor API.',
                'image'       => route('myvendor_sending_icon'),
                // create_at_omit => map admin derives from 'type'
            ];
        });

        // (3) Lifecycle - only if the plugin needs cleanup on uninstall.
        Hook::add('delete_plugin', self::PLUGIN_NAME, function() {
            \App\Models\SendingServer::where('type', 'myvendor-driver-type')->forceDelete();
        });
    }
}

The driver class

The minimum-viable driver inherits from Apps\SendingServers\Drivers\AbstractDriver and should implement ProvidesConnectionFieldView marker (which gives the host a hint that this driver has its own connection blade):

namespace MyVendor\Sending;

use Acelle\Library\Send\Base;
use Acelle\Library\Contracts\ProvidesConnectionFieldView;
use Apps\SendingServers\Drivers\AbstractDriver;
use Apps\SendingServers\Drivers\TestResult;
use Apps\SendingServers\Drivers\TestResultBasic;

class MyVendorDriver extends AbstractDriver implements ProvidesConnectionFieldView
{
    public const TYPE = 'myvendor-api';

    public function getTypeDisplayName(): string { return 'MyVendor'; }
    public function getTypeDisplayIcon(): string { return '...'; } // Material Symbol ligature
    public function getTypeDisplayColor(): string { return 'text-chart-2'; }

    public function sendMessage(array $params): array // returns [] | SendResult
    {
        // Call vendor API to deliver message
        // $params['to'], $params['subject'], $params['html'], ...
        // $this->getApiToken() -- helper to fetch from the Sending Server row
        $senderMessageId = $this->callVendorApi($params);
        return SendResult::success($senderMessageId);
    }

    public function test(): TestResult
    {
        try {
            // !! pitfall 9.1 - MUST hit a real endpoint that requires auth.
            // ping() logic here
            return TestResult::success();
        } catch (\Throwable $e) {
            return TestResult::failure($e->getMessage());
        }
    }

    public function setupBeforeSend($messageId): void
    {
        // No-op for most drivers. Implement if vendor needs per-batch
        // setup — SPF/DKIM setup verification, identity feedback enable, etc.
    }

    public function validateOnSubmit(): array
    {
        $r = parent::validateOnSubmit();
        $r['api_key'] = 'required';
        $r['my_region'] = 'required|in:us,eu';
        return $r;
    }

    public function getConnectionFieldView(): string
    {
        return 'myvendor::sending-servers._fields_connection';
    }
}

The four service-name accessors (getServiceName, getServiceIcon, getServiceColor) are all UI-only — they power the picker card and the chosen-server header in the Sending Servers UI. send() and test() are the production hot-paths — every campaign sent through a server of this type calls send() once per recipient; every time an admin clicks Test, test() runs. setupBeforeSend() runs once at the start of a campaign batch — most drivers leave it empty.

Capability marker interfaces

Beyond the minimum surface, the host exposes a set of capability marker interfaces. The driver implements only the markers that apply — the host does instanceof checks at every call site, so a driver that does not implement ReceivesWebhooks simply skips the webhook route registration logic. Three (in particular) are available:

Connection-tab blade

The connection partial under resources/views/sending_servers/_fields_connection.blade.php renders only the form fields. The host wraps it in the <form>, the submit button, the validation alert, and the four-tab page chrome:

<div class="m-form group">
    <div class="row">
        <div class="col-md-6">
            <!-- trans('myvendor::messages.fields.api_key') -->
            <div class="form-group {{ $errors->has('api_key') ? 'has-error' : '' }}">
                <label class="m-form-required">{{ trans('myvendor::messages.api_key') }}</label>
                <div class="input-icon">
                   <i class="fa fa-key"></i>
                   <input type="text" 
                          name="api_key" 
                          value="{{ $server->getOption('api_key') ?: $server->config['api_key'] ?? '' }}" 
                          class="m-form-input {{ $errors->has('api_key') ? 'm-form-input-error' : '' }}" />
                </div>
                @if ($errors->has('api_key'))
                   <span class="help-block">{{ $errors->first('api_key') }}</span>
                @endif
                <p class="help-block">{{ trans('myvendor::messages.fields.api_key_help') }}</p>
            </div>
        </div>
    </div>

    <div class="row mt-10">
        <div class="col-md-12">
            <label class="m-form-label">{{ trans('myvendor::messages.fields.webhook_url') }}</label>
            <div class="bg-light p-3 rounded">
                <code>{{ $server->id ? server_url('driver-webhook', ['vendor'=>'myvendor', 'uid'=>$server->uid]) : trans('myvendor::messages.fields.webhook_url_not_available_yet') }}</code>
                <p class="help-block mt-2 italic">{{ trans('myvendor::messages.fields.webhook_url_help') }}</p>
            </div>
        </div>
    </div>
</div>

Three rules govern the partial:

• Only fields, no <form>, no submit button. The host owns the form wrapper. Adding your own submit fires the wrong save endpoint.
• Field name matches the config_keys payload + validateOnSubmit()'s keys. The host maps all request->api_key (etc.) through the JSON config column based on the keys you declared.
• Read existing values via $server->getOption('api_key', null), NOT $server->api_key. The latter happens to work through a legacy __get() attribute fallback but is muddier and not contractually stable.

The validation pipeline

When an admin clicks Save on the Sending Server form, the host runs your driver's validation in two phases:

// In the host's SendingServerController::store

public function store(...) {
    // phase 1
    $sendingServer->validateOnSubmit($request->all()); // Laravel validation pass

    // phase 2
    if ($sendingServer->test()) { // driver's test() call
        $sendingServer->status = 'active';
    } else {
        $sendingServer->status = 'inactive';
    }
}

Your driver controls two failure modes:

• Field-level (Phase 1) — rules in validateOnSubmit(). The host auto-maps each rule to its corresponding name="..." field in your blade, where @error('my_api_key') renders inline.
• Connection-level (Phase 2) — anything thrown or TestResult::failure(...)-returned from test(). The host surfaces it on a synthetic connection field rendered in the validation-summary alert at the top of the form.

Five pitfalls from the Postal plugin

These are real bugs the Postal MTA plugin hit. Knowing them up front saves the next driver author hours of debugging.

Activate + verify recipe

After dropping the plugin folder under storage/app/plugins/{vendor}/{name}/, register and activate it through linker, then run five smoke checks:

# 1. Register the plugin with core
php artisan linker -y plugin/install/storage/app/plugins/myvendor/sending/

# 2. Activate (fires activate_plugin hook)
php artisan linker -y activate:myvendor/sending/

# 3. Verify the Driver Registered
php artisan linker -- SendingServerService:registry:all();
echo \Senddera\Library\Send\Registry::all(); // finds 'myvendor-api' => '...'

# 4. Verify config keys auto-routed
php artisan linker -- SendingServerController:validateOnSubmit();
echo in_array('my_api_key', $keys, true); // => 'YES'

# 5. Verify the connection-blade view is namespaced
php artisan linker -- View:exists('myvendor::sending-servers._fields_connection'); // => 'YES'

UI smoke after the five checks pass:

1. Login as admin -> Sending Servers -> Create. The "MyVendor" block should now show up in the middle of the picker card grid.
2. Click your card. The form renders with the fields declared in validateOnSubmit(['cols']).
3. Save with valid credentials. The host runs Phase 1 rules (rules) then Phase 2 (driver->test()); both pass and the row commits.
4. UI edit again. Four tabs: Connection (your blade) + Configuration / Sender Identity / Warmup / (host-rendered).

Testing checklist

Filesystem template

The fastest path to a working plugin is cloning the Postal plugin and renaming. Six edits and a few search-and-replaces:

cp -r storage/app/plugins/rencontru/postal storage/app/plugins/myvendor/name/
cd storage/app/plugins/myvendor/name/

# 1. Edit composer.json - name, namespace, autoload psr-4
# 2. Rename src/PostalDriver.php -> Driver.php, update class name + TYPE
# 3. Edit ServiceProvider.php - PLUGIN_NAME, name, view namespace, hook payload
# 4. Edit resources/views/sending_servers/_fields_connection.blade.php
# 5. Adjust resources/lang/en/messages.php
# 6. Replace the Postal HTTP client vendor with your vendor client

The Postal plugin is a useful reference for shape but its API client is Postal-specific — replace, do not adapt. The acelle/api-showcase showcase the canonical plugin if you need a different reference for backend, sidebar UI, or admin pages.

Where to go next