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!

Gutenberg support

Blocks in Gutenberg rely on CSS, HTML5 and defaults not available in email clients. Dispatcher “converts” the block to be correctly (but not identically) displayed by email clients.

Generally, custom fonts and block custom styles are not supported. Glitches are expected in Outlook since it lacks support for some basic CSS (for example, max-width), and padding is just an option in Outlook; it is supported only on tables.

Paragraph. When a background is specified, and padding is not, a 24px padding is added. Font sizing is supported.

Image. Supported, and it should be responsive. Glitches expected on Outlook.

Gallery. Work in progress.

Group. Supported and used to set a background for multiple blocks. Flexible content organisation is not completely available. Full width version should work, useful to create a full stripe with a background colour. No padding is added by default.

Row. Actually, it is a Group block. It may work.

Heading. When a background is specified, and padding is not, a 24px padding is added.

Spacer. It should work.

Columns. Work in progress, they may work for simple cases.

Buttons. Supported. Not all layouts work on email clients as they do on a web page.

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 with the classic editor; 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)
• Gutenberg is an option to enable the block editor to create your emails
  • You can enable all blocks, but most of them won’t render correctly on email clients

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 Membership 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 requires very little coding. Let’s 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. For example you can create a contact this way:

$contact = new stdClass();
$contact->id = ...;
$contact->email = ...;

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 with a query. Note the column aliases in the query to have objects compatible with the contact specifications.

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 caching 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.

Advanced features

How to add settings to an Audience

If your audience is parametric, you can show its settings on the email editing page. Extend your class with a new method: form().

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 key 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 NOT to 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).

For example, the Audiences plugin uses a mix of global and per email settings.

Target description

If the audience object implements the get_target_description($params) method, it is used when a (short) summary of the targeting options can be displayed (for example, on the email list). The method should return plain text.

Advanced filters and actions

Nothing by now.