alleyinteractive / wp-newsletter-builder

v0.9.0 2026-11-05 22:19 UTC

Requires

• php: ^8.3
• alleyinteractive/composer-wordpress-autoloader: ^1.0
• campaignmonitor/createsend-php: ^7.0
• sendgrid/sendgrid: ^8.1
• tijsverkoyen/css-to-inline-styles: ^2.2

Requires (Dev)

• alleyinteractive/alley-coding-standards: ^2.0
• alleyinteractive/wordpress-fieldmanager: ^1.6
• mantle-framework/testkit: ^1.1.2
• szepeviktor/phpstan-wordpress: ^2.0

GPL-2.0-or-later

• Alley Interactive

• alleyinteractive
• wp-newsletter-builder

Published on Packagist.org on 2026-11-05 22:20 UTC

README

Contributors: alleyinteractive

Tags: alleyinteractive, wp-newsletter-builder

Stable tag: 0.3.35

Requires at least: 6.2

Tested up to: 6.4.1

Requires PHP: 8.3

License: GPL v2 or later

Interface to manage email newsletters. Creates a Custom Post Type.

Installation

You can install the package via composer:

composer require alleyinteractive/wp-newsletter-builder

Usage

Activate the plugin in WordPress and use it like so:

$plugin = WP_Newsletter_Builder\WP_Newsletter_Builder\WP_Newsletter_Builder();
$plugin->perform_magic();

Enabling an Email Provider

The plugin supports multiple email providers. To enable an email provider, add the following code as a plugin or function in your theme wp-newsletter-builder-PROVIDER.php:

This decision was made so that only developers can switch email providers (but it may be that we want to create a settings page for this in the future.)

<?php
/**
 * Plugin Name: PROVIDER for WP Newsletter Builder
 * Description: Plugin to enable PROVIDER as an email provider for WP Newsletter Builder.
 * Version: 0.1.0
 * Author: Alley
 *
 * Text Domain: newsletter-testing
 * Domain Path: /languages/
 *
 * @package newsletter-testing
 */
add_filter( 'wp_newsletter_builder_selected_provider',
	fn( $provider ) => 'WP_Newsletter_Builder\Email_Providers\PROVIDER'
);

Null Provider

WP_Newsletter_Builder\Email_Providers\Null_Provider enables all Newsletter Builder functionality except sending email. Use it when newsletters are built in WordPress but sent from another tool: editors can draft newsletters and copy or download their HTML without an email service provider connection.

add_filter( 'wp_newsletter_builder_selected_provider',
	fn( $provider ) => 'WP_Newsletter_Builder\Email_Providers\Null_Provider'
);

With the Null provider selected:

• Publishing a newsletter doesn't send email or make any request to an email service provider.
• Email lists aren't required, and controls that depend on email service provider data (email lists, suppression groups, newsletter stats) are hidden.

Custom providers can opt out of sending the same way by adding a sends_email(): bool method that returns false.

Exporting Newsletter HTML

The newsletter editor has an Export HTML panel in the document settings sidebar, with buttons to copy the newsletter's HTML to the clipboard or download it as an .html file. The export renders the last saved version of the newsletter through the same template as the front-end view, with CSS inlined and absolute URLs, and works for drafts and published newsletters. It's available with any email provider to users who can edit the newsletter.

Filtering Post Types Available in the Post Picker

The plugin allows filtering of post types available in the Gutenberg post picker. The post picker appears in the wp-newsletter-builder/post block as a single post picker and in the wp-newsletter-builder/section block as a multiple post picker.

For example, to allow a custom podcast post type to appear in the post picker, along with the default post post type:

add_filter( 'wp_newsletter_builder_allowed_post_types',
  function( array $allowed_post_types ) {
    $allowed_post_types[] = 'podcast';
    return $allowed_post_types;
  }
);

Filtering Post Statuses Shown in Newsletters

Newsletters only show published posts. A post with any other status, such as a draft or private post, is left out of the newsletter's output, its export, and the email that's sent, even if it was picked in the editor.

To allow other statuses, filter wp_newsletter_builder_allowed_post_statuses. For example, to also show scheduled posts:

add_filter( 'wp_newsletter_builder_allowed_post_statuses',
  function( array $allowed_post_statuses ) {
    $allowed_post_statuses[] = 'future';
    return $allowed_post_statuses;
  }
);

Newsletters are public, so only allow statuses whose posts can be shown to anyone.

Styling Newsletters

Newsletters are rendered without the theme's styles, so the plugin removes the theme's styles from the newsletter and template editors to keep them close to the output. This works like turning off the editor's "Use theme styles" preference and also removes the site's Additional CSS. The editor still offers the theme's color and font size presets, but newsletters don't include their CSS.

To style newsletters, add CSS to the output with the wp_newsletter_builder_enqueue_styles action, and add the same CSS to the editor with the wp_newsletter_builder_editor_styles filter:

add_action( 'wp_newsletter_builder_enqueue_styles', function () {
  printf( '<style>%s</style>', file_get_contents( __DIR__ . '/newsletter.css' ) );
} );

add_filter( 'wp_newsletter_builder_editor_styles', function ( array $styles ) {
  $styles[] = [ 'css' => file_get_contents( __DIR__ . '/newsletter.css' ) ];
  return $styles;
} );

To keep the theme's styles in the editor instead:

add_filter( 'wp_newsletter_builder_remove_theme_editor_styles', '__return_false' );

Testing

Run npm run test to run Jest tests against JavaScript files. Run npm run test:watch to keep the test runner open and watching for changes.

Run npm run lint to run ESLint against all JavaScript files. Linting will also happen when running development or production builds.

Run composer test to run tests against PHPUnit and the PHP code in the plugin.

The entries directory and entry points

All directories created in the entries directory can serve as entry points and will be compiled with @wordpress/scripts into the build directory with an accompanied index.asset.php asset map.

Enqueuing Entry Points

You can also include an index.php file in the entry point directory for enqueueing or registering a script. This file will then be moved to the build directory and will be auto-loaded with the load_scripts() function in the functions.php file. Alternatively, if a script is to be enqueued elsewhere there are helper functions in the src/assets.php file for getting the assets.

Scaffold a block with create-block

Use the create-block command to create custom blocks with @wordpress/create-block and follow the prompts to generate all the block assets in the blocks/ directory. Block registration, script creation, etc will be scaffolded from the bin/create-block/templates/block/ templates. Run npm run build to compile and build the custom block. Blocks are enqueued using the load_scripts() function in src/assets.php.

Updating WP Dependencies

Update the WordPress dependency packages used in the project to their latest version.

To update @wordpress dependencies to their latest version use the packages-update command:

npx wp-scripts packages-update

This script provides the following custom options:

• --dist-tag – allows specifying a custom dist-tag when updating npm packages. Defaults to latest. This is especially useful when using @wordpress/dependency-extraction-webpack-plugin. It lets installing the npm dependencies at versions used by the given WordPress major version for local testing, etc. Example:

npx wp-scripts packages-update --dist-tag=wp-WPVERSION`

Where WPVERSION is the version of WordPress you are targeting. The version must include both the major and minor version (e.g., 6.1). For example:

npx wp-scripts packages-update --dist-tag=wp-6.1`

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

This project is actively maintained by Alley Interactive. Like what you see? Come work with us.

• [Alley Interactive](https://github.com/Alley Interactive)
• All Contributors

License

The GNU General Public License (GPL) license. Please see License File for more information.