Flavia Bernárdez Rodríguez

Create A Newsletter With The Block Editor (CANWBE)

Complete Documentation – English

🔄 Changelog

Version 1.3

  • Batch email sending system
  • WP Mail SMTP compatibility
  • Enhanced admin interface
  • Detailed logging

Version 1.2

  • Block editor support
  • Email template improvements
  • Minor bug fixes

Version 1.1

  • Basic newsletter functionality
  • Subscriber management
  • Subscription forms

Need help? Check the documentation on GitHub or create an issue for technical support.

📋 Table of Contents

  1. Introduction
  2. Installation
  3. Initial setup
  4. Creating a newsletter
  5. Subscriber management
  6. Batch email system
  7. Resending newsletters
  8. Advanced configuration
  9. Troubleshooting
  10. Hooks and filters
  11. FAQ

🎯 Introduction

Create A Newsletter With The Block Editor (CANWBE) is a WordPress plugin that allows you to create and send professional newsletters using WordPress’s native block editor (Gutenberg).

✨ Key features:

  • Visual editor: Use WordPress block editor
  • Batch sending: Smart system to prevent server overload
  • Subscriber management: Easily manage your subscriber list
  • SMTP compatibility: Works with WP Mail SMTP and other email plugins
  • Detailed logs: Complete tracking of sends and errors
  • Responsive: Newsletters that look great on all devices

🚀 Installation

Automatic installation:

  1. Go to Plugins → Add New
  2. Search for “Create A Newsletter With The Block Editor”
  3. Click “Install Now”
  4. Activate the plugin

Manual installation:

  1. Download the plugin from the repository
  2. Upload the folder to /wp-content/plugins/
  3. Activate the plugin from Plugins → Installed Plugins

System requirements:

  • WordPress 5.0 or higher
  • PHP 7.4 or higher
  • MySQL 5.6 or higher
  • Recommended PHP memory: 128MB minimum

⚙️ Initial setup

1. Plugin access

After activation, you’ll find:

  • Newsletter in the WordPress sidebar menu
  • Submenus: All newsletters, Add new, Email Batches

2. Basic configuration

  1. Go to Newsletter → Settings
  2. Configure:
    • Sender email
    • Sender name
    • Unsubscribe message
    • Confirmation page

3. SMTP configuration (Recommended)

For better delivery results, configure SMTP:

  • Install WP Mail SMTP or similar
  • Configure your email provider (Gmail, SendGrid, etc.)
  • Test sending before using the plugin

✍️ Creating a newsletter

1. New newsletter

  1. Go to Newsletter → Add new
  2. Enter a title for your newsletter
  3. Use the block editor to create content

2. Recommended blocks

  • Paragraph: For main text
  • Headings: For titles and sections
  • Image: For visual content
  • Button: For call-to-actions
  • Columns: For complex layouts
  • Spacer: To control spacing

3. Design best practices

  • Maximum width: 600px for email client compatibility
  • Images: Optimize size (maximum 1MB per image)
  • Colors: Use consistent palettes with your brand
  • Text: Keep paragraphs short and readable
  • CTAs: Use clear and prominent buttons

4. Preview

  • Use preview before publishing
  • Test on different devices
  • Verify all links

👥 Subscriber management

1. Who receives newsletters?

By default, newsletters are sent to:

  • Registered users in WordPress
  • Specific roles (configurable)
  • Custom lists (if configured)

2. Configure recipients

// In your theme's functions.php, you can filter subscribers:
add_filter('canwbe_newsletter_subscribers', function($subscribers, $post_id) {
    // Filter by role
    return array_filter($subscribers, function($user) {
        return in_array('subscriber', $user->roles);
    });
}, 10, 2);

3. Subscription form

Create a registration form:

<form method="post" action="">
    <input type="email" name="subscriber_email" required placeholder="Your email">
    <input type="hidden" name="action" value="canwbe_subscribe">
    <?php wp_nonce_field('canwbe_subscribe', 'canwbe_nonce'); ?>
    <button type="submit">Subscribe</button>
</form>

📬 Batch email system

1. How it works?

The plugin divides email sending into small batches to:

  • Avoid server timeouts
  • Reduce server load
  • Improve deliverability
  • Allow progress tracking

2. Batch configuration

Default configuration:

  • Emails per batch: 10
  • Delay between batches: 30 seconds
  • Maximum retries: 3
  • Retry delay: 5 minutes

3. Monitor sending

  1. Go to Newsletter → Email Batches
  2. You’ll see:
    • Batch status: Queued, Processing, Completed, Cancelled
    • Progress: Percentage completed
    • Statistics: Sent/Failed/Total
    • Actions: Cancel active batches

4. Batch states

  • 🔵 Queued: In queue, waiting for processing
  • 🟡 Processing: Actively sending emails
  • 🟢 Completed: Fully sent
  • 🔴 Cancelled: Cancelled by administrator
  • ❌ Failed: Critical error

🔄 Resending newsletters

✅ Recommended method: Duplication

  1. Copy the content from the original newsletter
  2. Create a new newsletter
  3. Modify the subject (e.g., “REMINDER: [Original title]”)
  4. Schedule sending

⚠️ Alternative method: Draft and republish

  1. Edit the existing newsletter
  2. Change status to “Draft”
  3. Update the post
  4. Publish again

Note: This method will resend to ALL subscribers.

🔧 Avoiding duplicate sends (Advanced)

// Filter users who already received the newsletter
add_filter('canwbe_newsletter_subscribers', function($subscribers, $post_id) {
    $already_sent = get_post_meta($post_id, '_canwbe_sent_users', true) ?: array();
    
    return array_filter($subscribers, function($subscriber) use ($already_sent) {
        return !in_array($subscriber->ID, $already_sent);
    });
}, 10, 2);

📋 Checklist before resending

  • [ ] Is it necessary to resend to EVERYONE?
  • [ ] Is the content still relevant?
  • [ ] Have you modified the email subject?
  • [ ] Have you added a note about the resend?
  • [ ] Have you reviewed content errors?

🔧 Advanced configuration

1. Customize batch settings

// In functions.php
add_filter('canwbe_batch_size', function($size) {
    return 25; // Change to 25 emails per batch
});

add_filter('canwbe_batch_delay', function($delay) {
    return 60; // Change to 60 seconds between batches
});

add_filter('canwbe_max_retries', function($retries) {
    return 5; // Change to 5 maximum retries
});

2. Customize email templates

// Modify email HTML
add_filter('canwbe_email_template', function($html, $content, $post_id) {
    // Your custom logic here
    return $html;
}, 10, 3);

3. Custom CSS for emails

// Add custom CSS
add_filter('canwbe_email_styles', function($css) {
    $css .= '
        .my-custom-class {
            color: #ff0000;
            font-weight: bold;
        }
    ';
    return $css;
});

4. Webhooks and notifications

// Notification when batch completes
add_action('canwbe_batch_completed', function($batch_id, $batch_data) {
    // Send webhook to your external system
    wp_remote_post('https://your-system.com/webhook', array(
        'body' => json_encode($batch_data),
        'headers' => array('Content-Type' => 'application/json')
    ));
}, 10, 2);

🛠️ Troubleshooting

❌ Common errors

1. “Call to undefined method get_batch_size()”

Solution: Add missing methods in batch-email-sender.php:

public static function get_batch_size() {
    return apply_filters('canwbe_batch_size', self::BATCH_SIZE);
}

public static function get_batch_delay() {
    return apply_filters('canwbe_batch_delay', self::BATCH_DELAY);
}

public static function get_max_retries() {
    return apply_filters('canwbe_max_retries', self::MAX_RETRIES);
}

2. Emails not sending

Possible causes:

  • Incorrect SMTP configuration
  • Hosting limits
  • Cache plugin interfering
  • Cron jobs not working

Solutions:

  1. Install WP Mail SMTP
  2. Contact hosting provider
  3. Exclude plugin from cache
  4. Verify WP Cron

3. Emails going to spam

Solutions:

  • Configure SPF, DKIM, DMARC
  • Use professional SMTP service
  • Avoid spam words in subject
  • Include unsubscribe link

📊 Logs and debugging

// Enable detailed logs
define('CANWBE_DEBUG', true);

// View logs in wp-content/debug.log
ini_set('log_errors', 1);
ini_set('error_log', ABSPATH . 'wp-content/debug.log');

🔍 Configuration verification

  1. PHP configuration: memory_limit, max_execution_time
  2. WP Cron: Verify it’s working correctly
  3. SMTP: Test sending
  4. Permissions: Correct files and directories

🎣 Hooks and filters

Available filters

// Modify subscribers
add_filter('canwbe_newsletter_subscribers', $callback, 10, 2);

// Modify email content
add_filter('canwbe_email_content', $callback, 10, 3);

// Modify email subject
add_filter('canwbe_email_subject', $callback, 10, 2);

// Modify batch configuration
add_filter('canwbe_batch_size', $callback);
add_filter('canwbe_batch_delay', $callback);
add_filter('canwbe_max_retries', $callback);

// Modify HTML template
add_filter('canwbe_email_template', $callback, 10, 3);

Available actions

// Before sending newsletter
add_action('canwbe_before_send_newsletter', $callback, 10, 2);

// After sending newsletter
add_action('canwbe_after_send_newsletter', $callback, 10, 2);

// When batch completes
add_action('canwbe_batch_completed', $callback, 10, 2);

// When email fails
add_action('canwbe_email_failed', $callback, 10, 3);

// When batch is cancelled
add_action('canwbe_batch_cancelled', $callback, 10, 1);

Usage examples

// Example: Log custom statistics
add_action('canwbe_batch_completed', function($batch_id, $batch_data) {
    update_option('my_newsletter_stats_' . $batch_data['post_id'], array(
        'sent' => $batch_data['sent_emails'],
        'failed' => $batch_data['failed_emails'],
        'date' => current_time('mysql')
    ));
});

// Example: Notify Slack when newsletter is sent
add_action('canwbe_after_send_newsletter', function($post_id, $subscribers) {
    $webhook_url = 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL';
    $message = sprintf(
        'Newsletter "%s" sent to %d subscribers',
        get_the_title($post_id),
        count($subscribers)
    );
    
    wp_remote_post($webhook_url, array(
        'body' => json_encode(array('text' => $message)),
        'headers' => array('Content-Type' => 'application/json')
    ));
});

❓ FAQ

How many emails can I send?

It depends on your hosting and SMTP configuration. Most hostings allow 100-300 emails/hour.

Is it compatible with WooCommerce?

Yes, you can send newsletters to WooCommerce customers by filtering user roles.

Does it work with Multisite?

The plugin works on each site independently in a Multisite installation.

Can I schedule newsletters?

Use WordPress’s “Schedule” function to send newsletters on specific dates.

How do I import subscribers?

You can import users to WordPress using plugins like “Import Users from CSV” and then use this plugin.

Is there a subscriber limit?

There’s no limit in the plugin, but your hosting and SMTP provider may have restrictions.

📞 Support

Report bugs

Request features

  • Use GitHub for new feature requests
  • Describe your need in detail
  • Include specific use cases

Contribute

  • Fork the repository on GitHub
  • Create a branch for your feature
  • Send a pull request with detailed description

📄 License

This plugin is licensed under GPL v2 or later.