Tools

Navigation: WP Admin > NimblyMail > Tools

The Tools page renders tab panes from a server-side registry. A Pro add-on registers tool tabs by filtering nimbly_mail_get_tools. For most tools — date pickers, text fields, action buttons — no Vue code is required. A narrow custom-renderer escape hatch exists for rule-builder UIs and other components that need their own Vue tree.

Anatomy of a Tool Descriptor

Each element in the nimbly_mail_get_tools array is an associative array with the following keys:

Key	Type	Required	Description
id	string	Yes	Unique tab identifier. Used as the router key.
label	string	Yes	Tab label visible in the UI.
icon	string	No	Ant Design icon name (e.g., BarChartOutlined).
description	string	No	Short paragraph rendered above the fields.
fields	array	No	Array of field descriptors. See Field Types.
actions	array	No	Array of action button descriptors (see below).
renderer	string	No	Custom renderer slug. Omit to use the generic renderer.

Action descriptor

Each entry in the actions array describes a button that posts to a REST endpoint and displays the response inline.

Key	Type	Required	Description
id	string	Yes	Unique action identifier within the tool.
label	string	Yes	Button label.
endpoint	string	Yes	REST endpoint path (relative to wp-json/).
method	string	No	HTTP method. Defaults to POST.
response_format	string	No	How to render the response. See below.

Adding a Generic Tool

A generic tool requires zero Vue code. Declare the descriptor in PHP and the built-in GenericTool.vue renders it.

add_filter(
    'nimbly_mail_get_tools',
    function ( array $tools ): array {
        $tools[] = array(
            'id'          => 'reports',
            'label'       => __( 'Reports', 'nimbly-mail-pro' ),
            'icon'        => 'BarChartOutlined',
            'description' => __( 'Generate a delivery summary for any date range.', 'nimbly-mail-pro' ),
            'fields'      => array(
                array(
                    'id'    => 'date_range',
                    'type'  => 'date-range',
                    'label' => __( 'Date Range', 'nimbly-mail-pro' ),
                    'group' => 'reports',
                ),
            ),
            'actions'     => array(
                array(
                    'id'              => 'generate',
                    'label'           => __( 'Generate Report', 'nimbly-mail-pro' ),
                    'endpoint'        => 'nimbly-mail-pro/v1/reports/generate',
                    'method'          => 'POST',
                    'response_format' => 'table',
                ),
            ),
        );
        return $tools;
    }
);

@since 1.0.0 — nimbly_mail_get_tools filter.

Signature: apply_filters( 'nimbly_mail_get_tools', array $tools )

• $tools — the current array of tool descriptors.

Returns: array

Available Action Response Formats

The response_format key controls how GenericTool.vue renders the HTTP response body after the action button is clicked.

Value	Rendering
text	Plain text paragraph.
json	Pretty-printed JSON inside a scrollable <pre> block.
code-block	Monospace <pre> with a copy-to-clipboard button.
table	Ant Design table. Response body must be { columns: [], rows: [] }.
none	Response is discarded; a success toast is shown instead.

Custom Renderers

For tools that need a bespoke Vue component — rule-builder UIs, chart pages, drag-and-drop editors — set the renderer key to a slug and register the component from JavaScript.

PHP side

add_filter(
    'nimbly_mail_get_tools',
    function ( array $tools ): array {
        $tools[] = array(
            'id'       => 'smart-routing',
            'label'    => __( 'Smart Routing', 'nimbly-mail-pro' ),
            'icon'     => 'ForkOutlined',
            'renderer' => 'smart-routing-rules',
        );
        return $tools;
    }
);

JavaScript side

Register the component using the global exposed by the free plugin. Ship a small JS entry point in your Pro plugin — not a full Vue bundle — that runs at admin-enqueue time:

// pro-tools.ts  (compiled and enqueued only on the Tools page)
import SmartRoutingRules from './components/SmartRoutingRules.vue';

// window.nimblyMail is exposed by the free plugin's built asset.
window.nimblyMail.registerToolRenderer( 'smart-routing-rules', SmartRoutingRules );

registerToolRenderer( slug, component ) adds the component to the customRenderers map inside ToolsView.vue. The free plugin’s render loop checks this map before falling back to GenericTool.

Note: The built-in Email Tester and Import tabs are themselves custom renderers registered under the slugs email-tester and import respectively. A Pro add-on can replace them by registering a component under the same slug — the last registration wins.

// Override the built-in Email Tester with a Pro version.
window.nimblyMail.registerToolRenderer( 'email-tester', ProEmailTester );