Emails

<?php
/**
 * Plugin Name:          Pocket Coffee Emails
 * Description:          Adds the "Roast ready" transactional email and a few email customisations.
 * Version:              0.1.0
 * Requires at least:    7.0
 * Requires PHP:         7.4
 * Requires Plugins:     woocommerce
 * WC requires at least: 11.2
 * WC tested up to:      11.2
 * Text Domain:          pocket-coffee-emails
 * License:              GPL-2.0-or-later
 *
 * @package PocketCoffeeEmails
 */

defined( 'ABSPATH' ) || exit;

define( 'POCKET_COFFEE_EMAILS_DIR', plugin_dir_path( __FILE__ ) );

// Declare compatibility with High-Performance Order Storage and the Cart and Checkout blocks.
add_action(
	'before_woocommerce_init',
	static function () {
		if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
			\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
			\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
		}
	}
);

/**
 * Register the email class. WC_Email exists only once WooCommerce has loaded,
 * so the class file is required inside the filter, not at plugin load time.
 *
 * @param array $emails Email objects, keyed by class name.
 * @return array
 */
function pocket_coffee_emails_register( $emails ) {
	require_once POCKET_COFFEE_EMAILS_DIR . 'includes/class-pocket-coffee-email-roast-ready.php';

	$emails['Pocket_Coffee_Email_Roast_Ready'] = new Pocket_Coffee_Email_Roast_Ready();

	return $emails;
}
add_filter( 'woocommerce_email_classes', 'pocket_coffee_emails_register' );

/**
 * Let WC_Emails run (or defer) our custom trigger like it does for core triggers:
 * the email class then listens to pocket_coffee_roast_ready_notification.
 *
 * @param string[] $actions Action names that trigger transactional emails.
 * @return string[]
 */
function pocket_coffee_emails_actions( $actions ) {
	$actions[] = 'pocket_coffee_roast_ready';

	return $actions;
}
add_filter( 'woocommerce_email_actions', 'pocket_coffee_emails_actions' );

/**
 * Brand the "Processing order" subject for Coffee Club members.
 *
 * @param string        $subject Formatted subject.
 * @param WC_Order|bool $order   Order the email is about.
 * @return string
 */
function pocket_coffee_emails_club_subject( $subject, $order ) {
	if ( $order instanceof WC_Order && $order->get_customer_id() && get_user_meta( $order->get_customer_id(), 'pocket_coffee_club', true ) ) {
		return '[Coffee Club] ' . $subject;
	}

	return $subject;
}
add_filter( 'woocommerce_email_subject_customer_processing_order', 'pocket_coffee_emails_club_subject', 10, 2 );

/**
 * Append brand CSS to the stylesheet that is inlined into every HTML email.
 *
 * @param string $css Email CSS.
 * @return string
 */
function pocket_coffee_emails_styles( $css ) {
	return $css . '
		.pocket-coffee-roast { background-color: #f3e3cf; border-radius: 4px; padding: 12px 16px; }
	';
}
add_filter( 'woocommerce_email_styles', 'pocket_coffee_emails_styles' );

/**
 * Write one log line for every email WooCommerce sends or fails to send.
 *
 * @param bool     $success Whether wp_mail() accepted the message.
 * @param string   $id      Email ID.
 * @param WC_Email $email   Email object.
 */
function pocket_coffee_emails_log( $success, $id, $email ) {
	$order_number = $email->object instanceof WC_Order ? $email->object->get_order_number() : '-';

	wc_get_logger()->info(
		sprintf( 'Email %s for order %s: %s', $id, $order_number, $success ? 'sent' : 'failed' ),
		array( 'source' => 'pocket-coffee-emails' )
	);
}
add_action( 'woocommerce_email_sent', 'pocket_coffee_emails_log', 10, 3 );

/**
 * Give the preview's dummy order a roast date, so the "Roast ready" preview is not empty.
 *
 * @param WC_Email $email Email object about to be previewed.
 * @return WC_Email
 */
function pocket_coffee_emails_prepare_preview( $email ) {
	if ( $email instanceof Pocket_Coffee_Email_Roast_Ready && $email->object instanceof WC_Order ) {
		$email->object->update_meta_data( '_pocket_coffee_roast_date', '2026-10-26' );
	}

	return $email;
}
add_filter( 'woocommerce_prepare_email_for_preview', 'pocket_coffee_emails_prepare_preview' );

/**
 * Opt the email in to the block email editor (only used when that feature is on).
 *
 * @param string[] $emails IDs of the emails that use the block email editor.
 * @return string[]
 */
function pocket_coffee_emails_block_editor( $emails ) {
	$emails[] = 'pocket_coffee_roast_ready';

	return $emails;
}
add_filter( 'woocommerce_transactional_emails_for_block_editor', 'pocket_coffee_emails_block_editor' );

/**
 * Register the pocket-coffee/roast-date personalization tag.
 *
 * @param \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry $registry Tag registry.
 * @return \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tags_Registry
 */
function pocket_coffee_emails_tags( $registry ) {
	$registry->register(
		new \Automattic\WooCommerce\EmailEditor\Engine\PersonalizationTags\Personalization_Tag(
			__( 'Roast date', 'pocket-coffee-emails' ),
			'pocket-coffee/roast-date',
			__( 'Pocket Coffee', 'pocket-coffee-emails' ),
			static function ( $context ) {
				$order = isset( $context['order'] ) ? $context['order'] : null;

				return $order instanceof WC_Order ? (string) $order->get_meta( '_pocket_coffee_roast_date' ) : '';
			},
			array(),
			null,
			array( 'woo_email' )
		)
	);

	return $registry;
}
add_filter( 'woocommerce_email_editor_register_personalization_tags', 'pocket_coffee_emails_tags' );

<?php
/**
 * "Roast ready" customer email.
 *
 * @package PocketCoffeeEmails
 */

defined( 'ABSPATH' ) || exit;

if ( ! class_exists( 'Pocket_Coffee_Email_Roast_Ready', false ) ) :

	/**
	 * Tells the customer that the beans of an order have been roasted.
	 */
	class Pocket_Coffee_Email_Roast_Ready extends WC_Email {

		/**
		 * Set the email ID, the templates and the trigger.
		 */
		public function __construct() {
			$this->id             = 'pocket_coffee_roast_ready';
			$this->customer_email = true;
			$this->title          = __( 'Roast ready', 'pocket-coffee-emails' );
			$this->description    = __( 'Sent to the customer when the beans of an order have been roasted.', 'pocket-coffee-emails' );
			$this->email_group    = 'order-updates';

			$this->template_html  = 'emails/pocket-coffee-roast-ready.php';
			$this->template_plain = 'emails/plain/pocket-coffee-roast-ready.php';
			$this->template_block = 'emails/block/pocket-coffee-roast-ready.php';
			$this->template_base  = POCKET_COFFEE_EMAILS_DIR . 'templates/';

			$this->placeholders = array(
				'{order_date}'   => '',
				'{order_number}' => '',
				'{roast_date}'   => '',
			);

			// Triggered through the pocket_coffee_roast_ready action (see woocommerce_email_actions).
			add_action( 'pocket_coffee_roast_ready_notification', array( $this, 'trigger' ), 10, 2 );

			// The parent constructor loads the saved settings, so it comes last.
			parent::__construct();
		}

		/**
		 * Default subject, translatable at run time.
		 *
		 * @return string
		 */
		public function get_default_subject() {
			return __( 'Your {site_title} beans are roasted', 'pocket-coffee-emails' );
		}

		/**
		 * Default heading.
		 *
		 * @return string
		 */
		public function get_default_heading() {
			return __( 'Fresh from the roaster', 'pocket-coffee-emails' );
		}

		/**
		 * Default text shown below the main content.
		 *
		 * @return string
		 */
		public function get_default_additional_content() {
			return __( 'Questions about brewing? Reply to this email or write to {store_email}.', 'pocket-coffee-emails' );
		}

		/**
		 * Send the email for one order.
		 *
		 * @param int           $order_id Order ID.
		 * @param WC_Order|bool $order    Order object, if the caller already has it.
		 */
		public function trigger( $order_id, $order = false ) {
			$this->setup_locale();

			if ( $order_id && ! is_a( $order, 'WC_Order' ) ) {
				$order = wc_get_order( $order_id );
			}

			if ( is_a( $order, 'WC_Order' ) ) {
				$this->object                         = $order;
				$this->recipient                      = $order->get_billing_email();
				$this->placeholders['{order_date}']   = wc_format_datetime( $order->get_date_created() );
				$this->placeholders['{order_number}'] = $order->get_order_number();
				$this->placeholders['{roast_date}']   = (string) $order->get_meta( '_pocket_coffee_roast_date' );
			}

			$this->send_notification();

			$this->restore_locale();
		}

		/**
		 * HTML body.
		 *
		 * @return string
		 */
		public function get_content_html() {
			return wc_get_template_html(
				$this->template_html,
				array(
					'order'              => $this->object,
					'email_heading'      => $this->get_heading(),
					'additional_content' => $this->get_additional_content(),
					'sent_to_admin'      => false,
					'plain_text'         => false,
					'email'              => $this,
				),
				'',
				$this->template_base
			);
		}

		/**
		 * Plain text body.
		 *
		 * @return string
		 */
		public function get_content_plain() {
			return wc_get_template_html(
				$this->template_plain,
				array(
					'order'              => $this->object,
					'email_heading'      => $this->get_heading(),
					'additional_content' => $this->get_additional_content(),
					'sent_to_admin'      => false,
					'plain_text'         => true,
					'email'              => $this,
				),
				'',
				$this->template_base
			);
		}
	}

endif;

<?php
/**
 * "Roast ready" email (HTML).
 *
 * This template can be overridden by copying it to yourtheme/woocommerce/emails/pocket-coffee-roast-ready.php.
 *
 * @package PocketCoffeeEmails\Templates
 * @version 0.1.0
 */

defined( 'ABSPATH' ) || exit;

/**
 * Email header.
 *
 * @hooked WC_Emails::email_header() Output the email header.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_header', $email_heading, $email );
?>

<p>
	<?php
	/* translators: %s: customer first name */
	printf( esc_html__( 'Hi %s,', 'pocket-coffee-emails' ), esc_html( $order->get_billing_first_name() ) );
	?>
</p>

<p class="pocket-coffee-roast">
	<?php
	printf(
		/* translators: 1: order number, 2: roast date */
		esc_html__( 'The beans of order #%1$s were roasted on %2$s and are on their way to the packing table.', 'pocket-coffee-emails' ),
		esc_html( $order->get_order_number() ),
		esc_html( $order->get_meta( '_pocket_coffee_roast_date' ) )
	);
	?>
</p>

<?php
/**
 * Order details table.
 *
 * @hooked WC_Emails::order_details() Shows the order details table.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email );

/**
 * Order meta data.
 *
 * @hooked WC_Emails::order_meta() Shows order meta data.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_order_meta', $order, $sent_to_admin, $plain_text, $email );

/**
 * Customer details.
 *
 * @hooked WC_Emails::customer_details() Shows customer details.
 * @hooked WC_Emails::email_address() Shows email address.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email );

if ( $additional_content ) {
	echo wp_kses_post( wpautop( wptexturize( $additional_content ) ) );
}

/**
 * Email footer.
 *
 * @hooked WC_Emails::email_footer() Output the email footer.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_footer', $email );

<?php
/**
 * "Roast ready" email (plain text).
 *
 * This template can be overridden by copying it to yourtheme/woocommerce/emails/plain/pocket-coffee-roast-ready.php.
 *
 * @package PocketCoffeeEmails\Templates\Plain
 * @version 0.1.0
 */

defined( 'ABSPATH' ) || exit;

echo "=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\n";
echo esc_html( wp_strip_all_tags( $email_heading ) );
echo "\n=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=\n\n";

/* translators: %s: customer first name */
echo sprintf( esc_html__( 'Hi %s,', 'pocket-coffee-emails' ), esc_html( $order->get_billing_first_name() ) ) . "\n\n";

echo sprintf(
	/* translators: 1: order number, 2: roast date */
	esc_html__( 'The beans of order #%1$s were roasted on %2$s and are on their way to the packing table.', 'pocket-coffee-emails' ),
	esc_html( $order->get_order_number() ),
	esc_html( $order->get_meta( '_pocket_coffee_roast_date' ) )
) . "\n\n";

/**
 * Order details table.
 *
 * @hooked WC_Emails::order_details() Shows the order details table.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_order_details', $order, $sent_to_admin, $plain_text, $email );

echo "\n----------------------------------------\n\n";

/**
 * Order meta data.
 *
 * @hooked WC_Emails::order_meta() Shows order meta data.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_order_meta', $order, $sent_to_admin, $plain_text, $email );

/**
 * Customer details.
 *
 * @hooked WC_Emails::customer_details() Shows customer details.
 * @hooked WC_Emails::email_address() Shows email address.
 * @since 0.1.0
 */
do_action( 'woocommerce_email_customer_details', $order, $sent_to_admin, $plain_text, $email );

echo "\n\n----------------------------------------\n\n";

if ( $additional_content ) {
	echo esc_html( wp_strip_all_tags( wptexturize( $additional_content ) ) );
	echo "\n\n----------------------------------------\n\n";
}

/**
 * Footer text, as saved in WooCommerce > Settings > Emails.
 *
 * @since 0.1.0
 */
$footer_text = apply_filters( 'woocommerce_email_footer_text', get_option( 'woocommerce_email_footer_text' ) );
echo wp_kses_post( $footer_text );

$sent = 0;
add_filter( 'pre_wp_mail', static function () use ( &$sent ) { ++$sent; return true; } );

do_action( 'pocket_coffee_roast_ready', 172 );
// The queue is flushed at shutdown; do it now to read the result.
wc_get_container()->get( \Automattic\WooCommerce\Internal\Email\DeferredEmailQueue::class )->dispatch();

echo "mails sent in this request: ", $sent, "\n";
$actions = as_get_scheduled_actions( array( 'hook' => 'woocommerce_send_queued_transactional_email', 'group' => 'woocommerce-emails', 'status' => ActionScheduler_Store::STATUS_PENDING, 'per_page' => 50 ), 'ids' );
echo "pending queued emails: ", count( $actions ), "\n";

mails sent in this request: 0
pending queued emails: 1

// One extra line in every order email, below the order table.
add_action(
	'woocommerce_email_order_meta',
	static function ( $order, $sent_to_admin, $plain_text ) {
		$roast_date = $order->get_meta( '_pocket_coffee_roast_date' );
		if ( '' === $roast_date || $plain_text ) {
			return;
		}
		echo '<p>' . esc_html( sprintf( 'Roasted on %s', $roast_date ) ) . '</p>';
	},
	20,
	3
);

// Send the admin "new order" notice to the roaster as well.
add_filter(
	'woocommerce_email_recipient_new_order',
	static function ( $recipient ) {
		return $recipient . ',roaster@example.test';
	}
);

function pocket_coffee_emails_styles( $css ) {
	return $css . '
		.pocket-coffee-roast { background-color: #f3e3cf; border-radius: 4px; padding: 12px 16px; }
	';
}
add_filter( 'woocommerce_email_styles', 'pocket_coffee_emails_styles' );

use Automattic\WooCommerce\Internal\Admin\EmailPreview\EmailPreview;

$preview = wc_get_container()->get( EmailPreview::class );
$preview->set_email_type( 'Pocket_Coffee_Email_Roast_Ready' );
echo 'subject: ', $preview->get_subject(), "\n";
$html = $preview->render();
echo trim( preg_replace( '/\s+/', ' ', wp_strip_all_tags( preg_replace( '/<style.*?<\/style>/s', '', $html ) ) ) ), "\n";
try {
	$preview->set_email_type( 'Not_An_Email' );
} catch ( InvalidArgumentException $e ) {
	echo 'unknown type: ', $e->getMessage(), "\n";
}

subject: Your Pocket Coffee Local beans are roasted
Pocket Coffee Local Pocket Coffee Local Fresh from the roaster Hi John, The beans of order #12345 were roasted on 2026-10-26 and are on their way to the packing table. Downloads Product Expires Download Dummy Downloadable Product (hello) October 27, 2026 Sample Download File.pdf Order summaryOrder #12345 (October 27, 2026) Product Quantity Price Dummy Product (hello) ×2 $50.00 Dummy Product Variation ×1 $20.00 Dummy Downloadable Product (hello) ×1 $15.00 Subtotal: $85.00 Discount: -$10.00 Shipping: Flat rate $5.00 Total: $80.00 Payment method: Direct bank transfer Customer note This is a customer note. Customers can add a note to their order on checkout. It can be multiple lines. If there’s no note, this section is hidden. Billing address John DoeCompany123 Fake StreetFaketown, CA 12345United States (US) 555-555-5555 john@company.com Shipping address John DoeCompany123 Fake StreetFaketown, CA 12345United States (US) 555-555-5555 Pocket Coffee LocalMadrid, Spain
unknown type: Invalid email type

use Automattic\WooCommerce\Utilities\FeaturesUtil;

$email_improvements_enabled = FeaturesUtil::feature_is_enabled( 'email_improvements' );
echo $email_improvements_enabled ? '<div class="email-introduction">' : '';

<?php
/**
 * "Roast ready" email: initial block template for the email editor.
 *
 * @package PocketCoffeeEmails\Templates\Block
 * @version 0.1.0
 */

use Automattic\WooCommerce\Internal\EmailEditor\BlockEmailRenderer;

defined( 'ABSPATH' ) || exit;
?>

<!-- wp:heading -->
<h2 class="wp-block-heading"><?php printf( /* translators: %s: customer first name tag */ esc_html__( 'Hi %s,', 'pocket-coffee-emails' ), '<!--[woocommerce/customer-first-name]-->' ); ?></h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p><?php printf( /* translators: 1: order number tag, 2: roast date tag */ esc_html__( 'The beans of order #%1$s were roasted on %2$s.', 'pocket-coffee-emails' ), '<!--[woocommerce/order-number]-->', '<!--[pocket-coffee/roast-date]-->' ); ?></p>
<!-- /wp:paragraph -->

<!-- wp:woocommerce/email-content {"lock":{"move":false,"remove":true}} -->
<div class="wp-block-woocommerce-email-content"><?php echo esc_html( BlockEmailRenderer::WOO_EMAIL_CONTENT_PLACEHOLDER ); ?></div>
<!-- /wp:woocommerce/email-content -->

use Automattic\WooCommerce\Utilities\FeaturesUtil;

echo 'block_email_editor: ', var_export( FeaturesUtil::feature_is_enabled( 'block_email_editor' ), true ), "\n";
$email = WC()->mailer()->get_emails()['Pocket_Coffee_Email_Roast_Ready'];
echo 'preheader field present: ', var_export( isset( $email->form_fields['preheader'] ), true ), "\n";
echo 'woo_email posts before: ', count( get_posts( array( 'post_type' => 'woo_email', 'post_status' => 'any', 'numberposts' => -1 ) ) ), "\n";
do_action( 'pocket_coffee_roast_ready', 172 ); // captured as before
echo 'woo_email posts after sending: ', count( get_posts( array( 'post_type' => 'woo_email', 'post_status' => 'any', 'numberposts' => -1 ) ) ), "\n";

block_email_editor: true
preheader field present: true
woo_email posts before: 0
woo_email posts after sending: 0

use Automattic\WooCommerce\Internal\EmailEditor\WCTransactionalEmails\WCTransactionalEmailPostsGenerator;

$email     = WC()->mailer()->get_emails()['Pocket_Coffee_Email_Roast_Ready'];
$generator = new WCTransactionalEmailPostsGenerator();

$post_id = $generator->create_draft( $email );
// ... send: still the file template ...
wp_update_post(
	array(
		'ID'           => $post_id,
		'post_status'  => 'publish',
		'post_content' => str_replace( 'were roasted on', 'left our roaster on', get_post( $post_id )->post_content ),
	)
);
// ... send: now the post ...
wp_delete_post( $post_id, true );
// ... send: the file template again.

created post 194 type=woo_email status=draft title=Roast ready
email type meta: pocket_coffee_roast_ready
draft exists, file template still renders: ... The beans of order #172 were roasted on 2026-10-26. ...
published and edited: ... The beans of order #172 left our roaster on 2026-10-26. ...
posts left: 0
after deleting the post: ... The beans of order #172 were roasted on 2026-10-26. ...