Extensibility (Pro Add-ons)

NimblyMail is built to be extended. A companion Pro plugin — or any third-party code — can register new mailers, tool tabs, dashboard widgets, REST endpoints, and admin pages without forking NimblyMail or shipping a Vue bundle for common controls. The hooks listed here ship as 1.0.0 public API.

Hook Reference

Filters

Filter	Purpose	Docs
nimbly_mail_mailers	Register a new mailer class.	Mailers
nimbly_mail_options_defaults	Register default values for new option groups.	Mailers
nimbly_mail_options_constants_map	Register wp-config.php constant names for new option groups.	Mailers
nimbly_mail_options_sensitive_fields	Register fields that are AES-encrypted at rest and masked in REST.	Mailers
nimbly_mail_get_tools	Register tool tabs in the Tools admin page.	Tools
nimbly_mail_dashboard_widgets	Inject widgets into the single-site dashboard.	Dashboard Widgets
nimbly_mail_network_dashboard_widgets	Inject widgets into the network dashboard (multisite only).	Dashboard Widgets
nimbly_mail_alert_recipients	Filter failure-alert recipients.	Secondary Hooks
nimbly_mail_alert_subject	Filter failure-alert subject line.	Secondary Hooks
nimbly_mail_alert_body	Filter failure-alert message body.	Secondary Hooks
nimbly_mail_email_controls	Append WordPress notification toggles (e.g., WooCommerce emails).	Secondary Hooks
nimbly_mail_log_query_args	Filter log query arguments before the query is built.	Secondary Hooks
nimbly_mail_log_items	Filter log rows returned from the query.	Secondary Hooks
nimbly_mail_log_row	Filter a single log row in the REST response.	Secondary Hooks

Actions

Action	Purpose	Docs
nimbly_mail_register_rest_routes	Register Pro REST controllers during rest_api_init.	REST API
nimbly_mail_admin_menu	Register Pro admin submenu pages during admin_menu.	Admin Pages
nimbly_mail_network_admin_menu	Register Pro network admin submenu pages during network_admin_menu.	Admin Pages
nimbly_mail_alert_sent	Fires after a failure alert is sent.	Secondary Hooks

Hello World — Minimal mu-plugin

The following mu-plugin demonstrates the overall extensibility loop: registering a mailer, adding a tool tab, and injecting a dashboard widget. Drop this file into wp-content/mu-plugins/ to verify the integration points work end to end.

<?php
/**
 * NimblyMail Pro — Hello World proof-of-concept.
 *
 * Drop in wp-content/mu-plugins/ for testing. Remove before going live.
 */

defined( 'ABSPATH' ) || exit;

// 1. Register a minimal stub mailer.
add_filter(
    'nimbly_mail_mailers',
    function ( array $mailers ): array {
        $mailers['hello-world'] = new Hello_World_Mailer();
        return $mailers;
    }
);

// 2. Register defaults so Options knows about the group.
add_filter(
    'nimbly_mail_options_defaults',
    function ( array $defaults ): array {
        $defaults['hello_world'] = array( 'api_key' => '' );
        return $defaults;
    }
);

// 3. Mark the api_key as sensitive (AES-encrypted at rest, masked in REST).
add_filter(
    'nimbly_mail_options_sensitive_fields',
    function ( array $sensitive ): array {
        $sensitive['hello_world.api_key'] = true;
        return $sensitive;
    }
);

// 4. Add a tool tab — no Vue required.
add_filter(
    'nimbly_mail_get_tools',
    function ( array $tools ): array {
        $tools[] = array(
            'id'          => 'hello-world',
            'label'       => 'Hello World',
            'icon'        => 'SmileOutlined',
            'description' => 'A minimal tool tab added by a mu-plugin.',
            'fields'      => array(
                array(
                    'id'    => 'greeting',
                    'type'  => 'text',
                    'label' => 'Greeting',
                    'value' => 'Hello, NimblyMail!',
                ),
            ),
            'actions'     => array(
                array(
                    'id'              => 'say-hello',
                    'label'           => 'Say Hello',
                    'endpoint'        => '/wp-json/hello-world/v1/greet',
                    'method'          => 'POST',
                    'response_format' => 'text',
                ),
            ),
        );
        return $tools;
    }
);

// 5. Inject a stat-card dashboard widget.
add_filter(
    'nimbly_mail_dashboard_widgets',
    function ( array $widgets ): array {
        $widgets[] = array(
            'id'       => 'hello-world-stat',
            'type'     => 'stat-card',
            'label'    => 'Hello World',
            'icon'     => 'SmileOutlined',
            'position' => 'after-activity',
            'data'     => array(
                'value'    => 42,
                'unit'     => 'greetings',
                'trend'    => 'up',
            ),
        );
        return $widgets;
    }
);

/**
 * Stub mailer used by the Hello World mu-plugin.
 *
 * @since 1.0.0 Added as a proof-of-concept extensibility example.
 */
class Hello_World_Mailer extends NimblyMailMailersAbstractMailer {

    /**
     * Return the mailer slug.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @return string The unique mailer slug.
     */
    public function get_slug(): string {
        return 'hello-world';
    }

    /**
     * Return the human-readable mailer title.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @return string The mailer title.
     */
    public function get_title(): string {
        return 'Hello World';
    }

    /**
     * Return the mailer description shown on the connection card.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @return string The mailer description.
     */
    public function get_description(): string {
        return 'A stub mailer for demonstration purposes.';
    }

    /**
     * Return the settings section descriptor for this mailer.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @return array The settings section descriptor.
     */
    public function get_settings_fields(): array {
        return array(
            'id'     => 'hello_world_settings',
            'title'  => 'Hello World Settings',
            'fields' => array(
                array(
                    'id'    => 'api_key',
                    'group' => 'hello_world',
                    'type'  => 'password',
                    'label' => 'API Key',
                ),
            ),
        );
    }

    /**
     * Configure PHPMailer for this mailer.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @param PHPMailerPHPMailerPHPMailer $phpmailer The PHPMailer instance.
     *
     * @return void
     */
    public function configure( PHPMailerPHPMailerPHPMailer $phpmailer ): void {
        // Stub — no real transport configured.
    }

    /**
     * Return whether this mailer is ready to send.
     *
     * @since 1.0.0 Added as a proof-of-concept extensibility example.
     *
     * @return bool True when the mailer has enough configuration to send.
     */
    public function is_ready(): bool {
        return false;
    }
}