Introduce email_group field in WC_Email (#60665)

yuliyan · web-flow · commit 95f88a1927a5 · 2025-08-29T18:02:22.000+03:00
* Introduce `email_group` field in WC_Email

* Add changelog

* Use slugs for $email_group property

* Fix lint errors and address coderabbitai suggestions
diff --git a/plugins/woocommerce/changelog/wooprd-800-add-api-for-notification-listing b/plugins/woocommerce/changelog/wooprd-800-add-api-for-notification-listing
@@ -0,0 +1,4 @@
+Significance: minor
+Type: add
+
+Introduce `email_group` field in WC_Email
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-cancelled-order.php b/plugins/woocommerce/includes/emails/class-wc-email-cancelled-order.php
@@ -31,6 +31,7 @@ class WC_Email_Cancelled_Order extends WC_Email {
 		public function __construct() {
 			$this->id             = 'cancelled_order';
 			$this->title          = __( 'Cancelled order', 'woocommerce' );
+			$this->email_group    = 'orders';
 			$this->template_html  = 'emails/admin-cancelled-order.php';
 			$this->template_plain = 'emails/plain/admin-cancelled-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-cancelled-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-cancelled-order.php
@@ -32,6 +32,7 @@ public function __construct() {
 			$this->id             = 'customer_cancelled_order';
 			$this->customer_email = true;
 			$this->title          = __( 'Cancelled order', 'woocommerce' );
+			$this->email_group    = 'order-exceptions';
 			$this->template_html  = 'emails/customer-cancelled-order.php';
 			$this->template_plain = 'emails/plain/customer-cancelled-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-completed-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-completed-order.php
@@ -30,6 +30,7 @@ public function __construct() {
 			$this->id             = 'customer_completed_order';
 			$this->customer_email = true;
 			$this->title          = __( 'Completed order', 'woocommerce' );
+			$this->email_group    = 'order-processing';
 			$this->template_html  = 'emails/customer-completed-order.php';
 			$this->template_plain = 'emails/plain/customer-completed-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-failed-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-failed-order.php
@@ -30,6 +30,7 @@ public function __construct() {
 			$this->id             = 'customer_failed_order';
 			$this->customer_email = true;
 			$this->title          = __( 'Failed order', 'woocommerce' );
+			$this->email_group    = 'order-exceptions';
 			$this->template_html  = 'emails/customer-failed-order.php';
 			$this->template_plain = 'emails/plain/customer-failed-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-created.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-created.php
@@ -38,6 +38,7 @@ public function __construct() {
 			$this->id             = 'customer_fulfillment_created';
 			$this->customer_email = true;
 			$this->title          = __( 'Fulfillment created', 'woocommerce' );
+			$this->email_group    = 'order-processing';
 			$this->template_html  = 'emails/customer-fulfillment-created.php';
 			$this->template_plain = 'emails/plain/customer-fulfillment-created.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-deleted.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-deleted.php
@@ -38,6 +38,7 @@ public function __construct() {
 			$this->id             = 'customer_fulfillment_deleted';
 			$this->customer_email = true;
 			$this->title          = __( 'Fulfillment deleted', 'woocommerce' );
+			$this->email_group    = 'order-processing';
 			$this->template_html  = 'emails/customer-fulfillment-deleted.php';
 			$this->template_plain = 'emails/plain/customer-fulfillment-deleted.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-updated.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-fulfillment-updated.php
@@ -38,6 +38,7 @@ public function __construct() {
 			$this->id             = 'customer_fulfillment_updated';
 			$this->customer_email = true;
 			$this->title          = __( 'Fulfillment updated', 'woocommerce' );
+			$this->email_group    = 'order-processing';
 			$this->template_html  = 'emails/customer-fulfillment-updated.php';
 			$this->template_plain = 'emails/plain/customer-fulfillment-updated.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-invoice.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-invoice.php
@@ -35,6 +35,7 @@ public function __construct() {
 			$this->id             = 'customer_invoice';
 			$this->customer_email = true;
 			$this->title          = __( 'Order details', 'woocommerce' );
+			$this->email_group    = 'payments';
 			$this->template_html  = 'emails/customer-invoice.php';
 			$this->template_plain = 'emails/plain/customer-invoice.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-new-account.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-new-account.php
@@ -65,6 +65,7 @@ public function __construct() {
 			$this->id             = 'customer_new_account';
 			$this->customer_email = true;
 			$this->title          = __( 'New account', 'woocommerce' );
+			$this->email_group    = 'accounts';
 			$this->description    = __( 'Send an email to customers notifying them that they have created an account', 'woocommerce' );
 			$this->template_html  = 'emails/customer-new-account.php';
 			$this->template_plain = 'emails/plain/customer-new-account.php';
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-note.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-note.php
@@ -37,6 +37,7 @@ public function __construct() {
 			$this->id             = 'customer_note';
 			$this->customer_email = true;
 			$this->title          = __( 'Customer note', 'woocommerce' );
+			$this->email_group    = 'order-exceptions';
 			$this->template_html  = 'emails/customer-note.php';
 			$this->template_plain = 'emails/plain/customer-note.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-on-hold-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-on-hold-order.php
@@ -30,6 +30,7 @@ public function __construct() {
 			$this->id             = 'customer_on_hold_order';
 			$this->customer_email = true;
 			$this->title          = __( 'Order on-hold', 'woocommerce' );
+			$this->email_group    = 'order-exceptions';
 			$this->template_html  = 'emails/customer-on-hold-order.php';
 			$this->template_plain = 'emails/plain/customer-on-hold-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-pos-completed-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-pos-completed-order.php
@@ -35,6 +35,7 @@ public function __construct() {
 			$this->id             = 'customer_pos_completed_order';
 			$this->customer_email = true;
 			$this->title          = __( 'POS completed order', 'woocommerce' );
+			$this->email_group    = 'payments';
 			$this->template_html  = 'emails/customer-pos-completed-order.php';
 			$this->template_plain = 'emails/plain/customer-pos-completed-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-pos-refunded-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-pos-refunded-order.php
@@ -49,6 +49,7 @@ public function __construct() {
 			$this->customer_email = true;
 			$this->id             = 'customer_pos_refunded_order';
 			$this->title          = __( 'POS refunded order', 'woocommerce' );
+			$this->email_group    = 'payments';
 			$this->template_html  = 'emails/customer-pos-refunded-order.php';
 			$this->template_plain = 'emails/plain/customer-pos-refunded-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-processing-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-processing-order.php
@@ -31,6 +31,7 @@ public function __construct() {
 			$this->customer_email = true;
 
 			$this->title          = __( 'Processing order', 'woocommerce' );
+			$this->email_group    = 'order-processing';
 			$this->template_html  = 'emails/customer-processing-order.php';
 			$this->template_plain = 'emails/plain/customer-processing-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-refunded-order.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-refunded-order.php
@@ -46,6 +46,7 @@ public function __construct() {
 			$this->customer_email = true;
 			$this->id             = 'customer_refunded_order';
 			$this->title          = __( 'Refunded order', 'woocommerce' );
+			$this->email_group    = 'order-exceptions';
 			$this->template_html  = 'emails/customer-refunded-order.php';
 			$this->template_plain = 'emails/plain/customer-refunded-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-customer-reset-password.php b/plugins/woocommerce/includes/emails/class-wc-email-customer-reset-password.php
@@ -65,6 +65,8 @@ public function __construct() {
 			$this->template_html  = 'emails/customer-reset-password.php';
 			$this->template_plain = 'emails/plain/customer-reset-password.php';
 
+			$this->email_group = 'accounts';
+
 			// Trigger.
 			add_action( 'woocommerce_reset_password_notification', array( $this, 'trigger' ), 10, 2 );
 
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-failed-order.php b/plugins/woocommerce/includes/emails/class-wc-email-failed-order.php
@@ -31,6 +31,7 @@ class WC_Email_Failed_Order extends WC_Email {
 		public function __construct() {
 			$this->id             = 'failed_order';
 			$this->title          = __( 'Failed order', 'woocommerce' );
+			$this->email_group    = 'orders';
 			$this->template_html  = 'emails/admin-failed-order.php';
 			$this->template_plain = 'emails/plain/admin-failed-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email-new-order.php b/plugins/woocommerce/includes/emails/class-wc-email-new-order.php
@@ -31,6 +31,7 @@ class WC_Email_New_Order extends WC_Email {
 		public function __construct() {
 			$this->id             = 'new_order';
 			$this->title          = __( 'New order', 'woocommerce' );
+			$this->email_group    = 'orders';
 			$this->template_html  = 'emails/admin-new-order.php';
 			$this->template_plain = 'emails/plain/admin-new-order.php';
 			$this->placeholders   = array(
diff --git a/plugins/woocommerce/includes/emails/class-wc-email.php b/plugins/woocommerce/includes/emails/class-wc-email.php
@@ -164,6 +164,13 @@ class WC_Email extends WC_Settings_API {
 	 */
 	protected $customer_email = false;
 
+	/**
+	 * Email group slug.
+	 *
+	 * @var string
+	 */
+	public $email_group = '';
+
 	/**
 	 *  List of preg* regular expression patterns to search for,
 	 *  used in conjunction with $plain_replace.
@@ -429,6 +436,51 @@ public function restore_locale() {
 		}
 	}
 
+	/**
+	 * Get available email groups with their titles.
+	 *
+	 * @since 10.3.0
+	 * @return array Associative array of email group slugs => titles.
+	 */
+	public function get_email_groups() {
+		$email_groups = array(
+			'accounts'         => __( 'Accounts', 'woocommerce' ),
+			'orders'           => __( 'Orders', 'woocommerce' ),
+			'order-processing' => __( 'Order processing', 'woocommerce' ),
+			'order-exceptions' => __( 'Order exceptions', 'woocommerce' ),
+			'payments'         => __( 'Payments', 'woocommerce' ),
+		);
+
+		/**
+		 * Filter the available email groups.
+		 *
+		 * @since 10.3.0
+		 * @param array $email_groups Associative array of email group slugs => titles.
+		 */
+		return apply_filters( 'woocommerce_email_groups', $email_groups );
+	}
+
+	/**
+	 * Get the title for the current email group.
+	 *
+	 * @since 10.3.0
+	 * @return string The email group title. Falls back to the email group slug if not found.
+	 */
+	public function get_email_group_title() {
+		$email_groups = $this->get_email_groups();
+		$title        = isset( $email_groups[ $this->email_group ] ) ? $email_groups[ $this->email_group ] : $this->email_group;
+
+		/**
+		 * Filter the email group title.
+		 *
+		 * @since 10.3.0
+		 * @param string $title The email group title.
+		 * @param string $email_group The email group slug.
+		 * @param array $email_groups Associative array of email group slugs => titles.
+		 */
+		return (string) apply_filters( 'woocommerce_email_group_title', $title, $this->email_group, $email_groups );
+	}
+
 	/**
 	 * Get email subject.
 	 *
