Navigation: NimblyMail > Settings > Connection
A Pro add-on registers a new email provider by extending NimblyMailMailersAbstractMailer and hooking into nimbly_mail_mailers. Once registered, the mailer appears automatically in the Connection tab card picker, its settings section is rendered under the card, and it participates in the setup wizard — without editing any core file.
Registering a Mailer
Step 1 — Implement the mailer class
Every mailer extends NimblyMailMailersAbstractMailer and implements five methods. The example below shows a complete Postmark mailer.
<?php
defined( 'ABSPATH' ) || exit;
use NimblyMailMailersAbstractMailer;
use PHPMailerPHPMailerPHPMailer;
/**
* Postmark mailer for NimblyMail Pro.
*
* Sends mail via the Postmark SMTP API.
*
* @since 1.0.0 Added Postmark mailer support.
*/
class NimblyMail_Pro_Postmark_Mailer extends AbstractMailer {
/**
* Return the unique mailer slug.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @return string The mailer slug.
*/
public function get_slug(): string {
return 'postmark';
}
/**
* Return the human-readable mailer title.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @return string The mailer title shown on the connection card.
*/
public function get_title(): string {
return 'Postmark';
}
/**
* Return the short description shown on the connection card.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @return string The mailer description.
*/
public function get_description(): string {
return __( 'Send transactional email via Postmark's reliable delivery infrastructure.', 'nimbly-mail-pro' );
}
/**
* Return the settings section descriptor for this mailer.
*
* The returned array must follow the section shape expected by
* SettingsProvider: { id, title, description?, fields[] }.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @return array The section descriptor.
*/
public function get_settings_fields(): array {
return array(
'id' => 'postmark_settings',
'title' => __( 'Postmark Settings', 'nimbly-mail-pro' ),
'description' => __( 'Enter your Postmark Server API Token. You can find it under your Postmark server's API Tokens tab.', 'nimbly-mail-pro' ),
'fields' => array(
array(
'id' => 'token',
'group' => 'postmark',
'type' => 'password',
'label' => __( 'Server API Token', 'nimbly-mail-pro' ),
'placeholder' => 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
'required' => true,
),
array(
'id' => 'message_stream',
'group' => 'postmark',
'type' => 'text',
'label' => __( 'Message Stream', 'nimbly-mail-pro' ),
'default' => 'outbound',
'help' => __( 'Leave as "outbound" unless you have configured a dedicated stream.', 'nimbly-mail-pro' ),
),
),
);
}
/**
* Configure PHPMailer to send through Postmark's SMTP endpoint.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @param PHPMailer $phpmailer The PHPMailer instance passed by WordPress.
*
* @return void
*/
public function configure( PHPMailer $phpmailer ): void {
$token = nimbly_mail_options()->get( 'postmark', 'token' );
$phpmailer->isSMTP();
$phpmailer->Host = 'smtp.postmarkapp.com';
$phpmailer->Port = 587;
$phpmailer->SMTPAuth = true;
$phpmailer->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$phpmailer->Username = $token;
$phpmailer->Password = $token;
}
/**
* Return whether the mailer has enough configuration to send.
*
* @since 1.0.0 Added Postmark mailer support.
*
* @return bool True when the token is set.
*/
public function is_ready(): bool {
return '' !== nimbly_mail_options()->get( 'postmark', 'token' );
}
}Step 2 — Register via the filter
add_filter(
'nimbly_mail_mailers',
function ( array $mailers ): array {
$mailers['postmark'] = new NimblyMail_Pro_Postmark_Mailer();
return $mailers;
}
);@since 1.0.0 — The nimbly_mail_mailers filter already existed before 1.0.0. What changed in 1.0.0 is that registering a mailer here now automatically wires it into the Connection tab UI — no extra steps required.
After this filter runs, the Postmark card appears in Settings > Connection. Selecting it reveals the section returned by get_settings_fields(). The SettingsProvider loop builds the card list and section visibility from the registered mailers, so no core file needs editing.
Credentials and Constants
Three filters allow a Pro add-on to integrate its option groups into NimblyMail’s existing Options pipeline — giving the add-on encrypted storage, wp-config.php constant support, and REST masking automatically.
nimbly_mail_options_defaults
Registers default values for new option groups.
Signature: apply_filters( 'nimbly_mail_options_defaults', array $defaults )
$defaults— the full defaults array, keyedgroup => [ key => default_value ].
Returns: array
@since 1.0.0
add_filter(
'nimbly_mail_options_defaults',
function ( array $defaults ): array {
$defaults['postmark'] = array(
'token' => '',
'message_stream' => 'outbound',
);
return $defaults;
}
);nimbly_mail_options_constants_map
Maps a wp-config.php constant name to a group/key pair. When the constant is defined, the field becomes read-only in the UI and the REST layer ignores any incoming write for that field.
Signature: apply_filters( 'nimbly_mail_options_constants_map', array $map )
$map— the full constants map, keyedgroup => [ key => CONSTANT_NAME ].
Returns: array
@since 1.0.0
add_filter(
'nimbly_mail_options_constants_map',
function ( array $map ): array {
$map['postmark'] = array(
'token' => 'NIMBLY_MAIL_POSTMARK_TOKEN',
);
return $map;
}
);With the above filter in place, adding define( 'NIMBLY_MAIL_POSTMARK_TOKEN', 'your-token' ) to wp-config.php locks the token field with a "Defined in wp-config.php" indicator and prevents it from being overwritten via the Settings UI or REST API.
nimbly_mail_options_sensitive_fields
Marks a group/key pair as sensitive. Sensitive fields are encrypted with AES-256-CBC + HMAC-SHA256 before being written to the database and are returned as ******** in all REST responses.
Signature: apply_filters( 'nimbly_mail_options_sensitive_fields', array $sensitive )
$sensitive— associative array keyed bygroup.keydot notation, value istrue.
Returns: array
@since 1.0.0
add_filter(
'nimbly_mail_options_sensitive_fields',
function ( array $sensitive ): array {
$sensitive['postmark.token'] = true;
return $sensitive;
}
);Combined example
In practice all three filters appear together in the same file:
add_filter(
'nimbly_mail_options_defaults',
function ( array $defaults ): array {
$defaults['postmark'] = array(
'token' => '',
'message_stream' => 'outbound',
);
return $defaults;
}
);
add_filter(
'nimbly_mail_options_constants_map',
function ( array $map ): array {
$map['postmark'] = array(
'token' => 'NIMBLY_MAIL_POSTMARK_TOKEN',
);
return $map;
}
);
add_filter(
'nimbly_mail_options_sensitive_fields',
function ( array $sensitive ): array {
$sensitive['postmark.token'] = true;
return $sensitive;
}
);With all three filters registered, postmark.token:
- Has a safe default (
'') soOptions::get()never returnsnullfor the group. - Is AES-encrypted before it reaches the database.
- Is returned as
********in the REST/settingsresponse. - Becomes read-only when
define( 'NIMBLY_MAIL_POSTMARK_TOKEN', '...' )is set inwp-config.php.