How to Create Custom WordPress Notification Recipients

WordPress notification recipients provide a unified interface for carriers to handle different types of notification destinations. The Recipient API separates logic and enables consistent handling of users, emails, roles, webhooks, and custom recipient types across all notification carriers.

As an example, the default Email Carrier registers a couple of Recipients - User selected from a list, Role, Administrator, Plain text email, etc. They all resolve to a flat array of emails. The Webhook provider registers URL recipients: GET, POST, PUT, etc.

Your Custom Recipient may allow you to select a User from a dropdown and parse a list of all selected Users to some kind of UUID, the one which is understood by your Custom Carrier.

Recipient class

use BracketSpace\Notification\Repository\Recipient\BaseRecipient;
use BracketSpace\Notification\Repository\Field;

/**
 * ExampleRecipient Recipient
 */
class ExampleRecipient extends BaseRecipient
{
    /**
     * Constructor
     */
    public function __construct()
    {
        parent::__construct(
            [
                'slug' => 'recipient_slug',
                'name' => __('Recipient', 'textdomain'),
                'default_value' => 'default',
            ]
        );
    }

    /**
     * Parses raw recipient value to something consumable by the Carrier.
     *
     * @param  string $value Raw value saved by the user.
     * @return array         Array of resolved values
     */
    public function parseValue($value = '')
    {
        if (empty($value)) {
            $value = [$this->getDefaultValue()];
        }

        $value = doSomethingWithTheUserValue($value);

        // Keep in mind you should return an array here.
        // This is because you may select a recipient which parses to multiple values.
        // Example: User Role recipient may parse to multiple emails.
        return [$value];

    }

    /**
     * Prints the Recipient field.
     *
     * @return Field
     */
    public function input()
    {
        // You should build an array of options here if you are using SelectField field.
        $opts = [
            'recipient1' => __('Recipient 1', 'textdomain'),
            'recipient2' => __('Recipient 2', 'textdomain'),
        ];

        // You can use other fields as well.
        return new Field\SelectField(
            [
                'label' => __('My Recipient', 'textdomain'),
                'name' => 'recipient', // Don't change this.
                'css_class' => 'recipient-value', // Don't change this.
                'value' => $this->getDefaultValue(),
                'pretty' => true,
                'options' => $opts,
            ] 
        );
    }
}

Registering the Recipient

note

Since version 8.0.0, recipients can be registered anytime on notification/init action and it doesn't matter if it's before or after the Carrier is registered.

use BracketSpace\Notification\Register;

add_action('notification/init', function() {
    // You need to provide the Carrier slug.
    Register::recipient('carrier-slug', new ExampleRecipient());
});