Dispatcher

Dispatcher is a cool plugin to send emails to an audience, for example, your WordPress users, but not limited to. Dispatcher is very extensible about contact extraction and targeting. I hope many integrations will be developed.

Installation

Support

You can contact me by email or on my Discord server.

Creating emails

It’s like creating a new post. Dispatcher uses the Classic editor, but you can enable the Block editor as well (Gutenberg). Possible problems with Guitenberg are that the generated HTML is not perfectly rendered by email clients. Dispatcher has a rendering engine to alleviate the problem, but not all blocks can be supported.

My motto is: care about the content and not only the presentation. I know it would not apply to everyone, that’s fine!

Useful tips and tricks

The excerpt can be set with a very short sentence, and it will be shown as an email content preview by some clients, usually Gmail.

Do not add left or right-aligned images; email clients mess up with them. But sometimes they work.

Expert tip. Do not add a big generic image or a giant logo on top of the email: the first part should immediately attract attention with content.

If you need to duplicate an email, you can use a post duplicator plugin like Yoast Duplicate Post, Duplicate Post, Post Duplicator.

Need help with images? Install Instant Image, a plugin that integrates Pexels and many other image sources.

Run out of ideas? Don’t be scared, use AI. There are many content writing assistants you can use, both with the classic and block editors.

Yes, you can use shortcodes in your emails; they’ll be rendered. Useful to include banners from Ads plugins. But remember: JavaScript and sophisticated HTML do not work on emails.

Settings

I’ve tried to keep the settings as simple as possible.

• The sender email is the email address your users see the email come from; by default, WP sets it to wordpress@domain.tld
• The speed is the number of emails per hour you can send: ask your hosting provider, they know
• The redirect email, if set, is where all emails are sent (for initial tests, I know you’re scared about mass mailing all the users)

A few setting details and problem solutions

• Never set as sender email an address like @gmail.com, @outlook.com and the like: those providers don’t want sites to send email with their domain, and probably you will be marked asa spammer
• If you need to send with your Gmail, Outlook, Yahoo, …, account, install an SMTP plugin and connect the site with those providers.
• Speed and WP scheduler: emails are sent every 15 minutes. Ask your hosting provider to set up a wp-cron.php trigger if you experience slowness.
• Database usage. Emails are “custom post types”; you can delete them and empty the trash to clean up the database. When uninstalled, Mailer removes even its own settings; nothing should be left behind.

Delivery problems and solutions

Dispatcher sends emails: that means it uses a WordPress function to send, but it has no control over what happens after. It’s like putting a letter in a mailbox.

The delivery process for an email is rather complex, and I suggest connecting the site with a reliable delivery service, like the SMTP offered by your hosting provider or a professional one.

Problematic email delivery is a common issue on WP, even with big hosting providers. Start here:

1. Install WP Mail Logging: it lists all the emails sent by WP
2. If an email is listed without errors
   • If you do not use an SMTP plugin, it means your hosting provider is dropping it; contact the provider
   • If you use an SMTP plugin, contact the provider of the SMTP service

Learn more about email delivery in WordPress.

Use a reliable email delivery service

Many of them have free plans, and they all can be connected to your site with an SMTP plugin.

• Gmail (for a very limited number of emails, you need an SMTP plugin able to connect)
• Outlook (not recommended due to too many problems)
• Sendgrid
• Mailjet
• Mailgun
• SMTP.com
• SMTP2Go
• ElasticEmail
• PostMark
• SparkPost

SMTP plugins

There are many, and usually you don’t need a pro version. I used:

• SimpleSMTP (it’s mine, the simpler one you can find…)
• WP Mail SMTP (the most diffused)
• FluentSMTP (very nice)
• SureSMTP

Audiences

Every email is sent to the selected audience. Dispatcher provides a set of default audiences, but it can be easily extended by third-party plugins. The developer section below explains the required simple steps.

Anyway, to start, the WP roles are a very powerful way to group your users and use them as an audience (probably this is the most common case).

Managing roles in WP

WP has some roles that can be used immediately, like Administrator, Contributor, Subscriber and so on, but they’re not so useful.

To extend the roles, you can use specific plugins, like:

• Members
• Publish Press Capabilities
• User Role Editor
• WPFront User Role Editor

Membership Plugins

If you manage a community of users, you may prefer install a membership plugin.

Those plugins not only manage the roles, but you can sell subscriptions, control the content visibility and so on. They manage the role change, for example, when a subscription expires.

• Paid Memberhip Pro (they have a free version)
• Ultimate Member
• MemberPress (do not confuse with their free Members plugin to manage roles)
• ProfilePress

---

How to add an audience

Adding audiences by third parties is really easy and require a very little coding. Le start with the simplest example.

1. Create your audience class

This class just need to have a few methods. I do not provide an interface or a base class right now.

Class MyAudience {
    function get_id() {
        return 'my-audience'; // must be unique, prefix it!
    }

    function get_name() {
        return 'My first audience';
    }

    function get_contacts($params) {
    }

    function get_total($params) {
    }
}

2. Register the audience

add_action('dispatcher_audiences_init', function () {
    dispatcher_register_audience(new MyAudience());
});

3. Provide data

Dispatcher asks the audience for the contacts to send the email to. It uses the get_contacts() method. A contact is an object with a unique id and an email address. More data will be supported in the future.

You need to return a list of contacts starting from the next one identified by the $params->last_contact_id. Ordering is important here, and it’s up to you to decide how to manage it!

You should return the maximum number of contacts specified (see the code), but a lower value is ok as well. When you return zero contacts, it means there are no more, and the sending can stop.

function get_contacts($params) {
    $params->max; // The max number of ocntact to return
    $params->last_contact_id; // The last contact ID processed
    $params->settings; // Per email audience settings, we see them later

    // Your extraction code

    return $contacts;
}

An example of a list of contacts using the WP users can be created as

global $wpdb;
// Note the strict "greater" than on the where clause and the aliases for ID and user_email
$contacts = $wpdb->get_results($wpdb->prepare("select ID as id, user_email as email from {$wpdb->users} where ID > %d order by ID ASC limit %d"), $params->last_contact_id, $params->max);

Why use a “last contact ID” instead of pagination or the like? Because, while sending, is not sure a whole page can be processed. So we need to start from the last processed contacts to continue, in the background, the sending work.

4. Provide a total contacts count

Contact extraction can be very complex, and it could be impossible to know the exact total without processing them all. Dispatcher does not rely on the exact number; you can optionally provide an estimate that helps in showing a progress percentage. Of course an exact value is appreciated.

This action is triggered only before starting the sending process. I can suggest computing the total with a background process and cache the value.

function get_total($params) {
    $params->settings; // Per email audience settings, we see them later

    // Your computation code

    return $total;
}

That’s all, you created a full working Audience.

How to add options to an Audience

If your audience is parametric, you can show its options on the email editing page. Extend your class with a new method (it could recall the WordPress widget structure):

Class MyAudience {
    function get_id() {
        return 'my-audience'; // must be unique, prefix it!
    }

    function get_name() {
        return 'My first audience';
    }

    function get_contacts($params) {
    }

    function get_total($params) {
    }

    // Correct escaping is up to you!
    function form($params) {
        echo '<label><input type="checkbox" name="audience_data[vip]"',
        isset($params->settings['vip']) ? ' checked' : '',
    }
}

All field names must be audience_data[xyz], and the name you specify is then available as $params->settings['xyz']. If you need to collect an array of values, for example, a set of checkboxes, you can use audience_data[xyz][] and $params->settings['xyz'] will be an array with all the values of the selected checkboxes.

Nothing special, it’s standard PHP.

Complex Audience settings

If you have complex settings for your audiences, it’s a good idea to NOT show them on the email editing page, but create an audience manager elsewhere and let the user select the Audience only by name (with only a few parameters if none).

Advanced filters and actions

Nothing by now.