Ever wondered how to create a custom email template that is visible in WooCommerce->Settings->Emails and can be managed and customized the same way as all other WooCommerce emails?
This post will guide you through WooCommerce’s inbuilt email templates structure & also understand how to create custom email templates in WooCommerce.
This can be done very easily using 2 WooCommerce email classes, WC_Emails and WC_Email. These are the 2 main email classes. The WC_Emails class is present in woocommerce/includes/class-wc-emails.php. The WC_Email class is present in woocommerce/includes/emails/class-wc-email.php.
Apart from these they have email classes for each of the emails and the templates as well. Some of the email classes present are class-wc-email-new-order.php, class-wc-email-failed-order.php and so on. All of these email classes are present in woocommerce/includes/emails/ folder.
The templates for these are present in woocommerce/templates/emails/ folder. The html templates are present in the folder itself, whereas the plain text templates are present in woocommerce/templates/emails/plain/ folder.
WC_Emails sends all the transactional emails. It loads all the available emails to be sent out when triggered (yes, we need to write those triggers for our custom emails!).
The WC_Email class is the one which is extended by each of the email template classes to add emails to WooCommerce. This is the class which helps us configure all the emails provided by WooCommerce.
It lists the emails in the Email Notifications page in WooCommerce->Settings->Emails.
The emails can be configured by clicking on the email title.
The above is the page where we can configure the settings for the New Order email, which is sent to the admin when a new order comes through.
When we create a custom email that extends the WooCommerce classes, we also are able to take advantage of all the WooCommerce email features.
Increase WooCommerce Store Sales
"WooCommerce Abandoned Cart Pro: This is a great, useful plugin. I am in a better position to retain customers that come to my site and do not complete an order. The plugin is simple to set up and I have received great support throughout. Keep up the good work Tyches software!" – Bess Obarotimi from Synatel Designs, VeeandJade.com
The advantages of extending these WooCommerce classes and their functionality are many. Such as:
- It allows your users to easily enable/disable the email template (You don’t need to provide any additional setting for the same).
- Users can add, edit recipients as desired.
- It can be customized the same way as any other WooCommerce email (so you don’t have to teach them how to do it 🙂 )
- You don’t need to write any css for the emails. Since they inherit the WooCommerce class, you just need to create the email content.
Here are the different components of a custom email that must be configured for it to be sent:
- Creating an email manager file.
- It will add the custom email trigger/s.
- It will queue up the custom email class.
- Creating the email class file.
- It will be a custom class which extends the WC_Email class.
- It will contain details like the ID, title etc.
- A list of the fields that will help the user configure the email like recipient, email subject, email heading and so on.
- Some functions related to sending the email (like getting the template, email subject and so on).
- The email templates. It is advisable to have 2 email templates.
- An HTML template.
- A plain text template.
In the below example, we will create a new custom email that will be sent to the admin for each item in an order, when the order status is changed to Pending Payment.
Step 1. Creating the Email Manager
The first thing that you need to do is create an email manager class. This class would queue up all your custom emails in the WooCommerce email queue. So in our case, it will queue up the pending payment notification email.
It can be created as a single file in the plugin for which you are trying to add a custom email. In a scenario where you are trying to add a custom email for a WooCommerce functionality, it is advisable to put the custom email files in a stand alone plugin.
We need to use the filter woocommerce_email_classes to include our email classes.
We also need to queue up our email triggers here. This has been done in the construct itself.
The email actions are triggered using the add_action for each value in the $email_actions array where we hook into the send_transactional_email function from the WC_Email class.
So in our case, custom_pending_email and custom_item_email are the email triggers. The custom_pending_email will be triggered when an order status is changed. We pass the Order ID in here. The function attached to this hook is in class-custom-email.php file. This function then gets the Item ID for all the items in the order and triggers the custom_item_email hook for each of the items.
The filter woocommerce_template_directory is a part of the WC_Email class. It is run when trying to get the template from the theme. Hence, we need to make sure we pass the correct directory name as needed.
Step 2. Creating the Email class
Next, create an email class for each of your custom emails. This class will extend the WC_Email class.
Since, we have only 1 custom email, we will create only 1 email class class-custom-email.php. Following the WooCommerce structure it is advisable to create the email class file in the /emails/ folder of your plugin.
The construct contains data like ID, title, description, heading and so on. It also contains a path to the template files.
We need to rewrite the below functions:
- get_content_html() – This function will get the html email template.
- get_content_plain() – This function will get the plain text email template.
- get_subject() – will return the email subject.
- get_heading() – will return the email heading.
- init_form_fields() – This function defines the fields which will be displayed in WooCommerce->Settings->Emails for the custom email.
We then need to attach functions to our email triggers. For e.g. our email actions are custom_pending_email and custom_item_email. So, in this class, we will attach functions to those.
The queue_notification function loops through all the items in an order and for each item triggers the custom_item_email event. This in turn will call the trigger function for each item.
We shall also create an object of the data that we need to pass to our email templates. This object will contain the item data in our case. It can hold any data as needed for the email.
As mentioned I’m going to send a custom email to the admin for each item in an order when the order status changes to pending. So the object that I create will contain basic details like order id, product ID, product name, quantity and the amount.
We have passed this object to the template in the get_content_html() and get_content_plain() functions.
Once the email class file is created, the email will be listed in WooCommerce->Settings->Emails.
The email settings can easily be edited by clicking on the email title.
Step 3. Creating the Email Templates
You will need to create 2 email templates: HTML & plain text template. Following the WooCommerce template structure, I usually create all my email templates in templates/emails/ folder of my plugins.
As you can see below, my email templates contain basic information about the product like product name, quantity and amount. Details as desired can be added in here.
Plain text template.
Finally add your email action triggers. I have added the trigger in the custom-email-manager.php file itself. The hook woocommerce_order_status_pending is triggered when an order status changes to Pending Payment.
In the function attached to the hook, we add a do_action for our email action i.e. custom_pending_email.
This is all that we need to do. This will send an email to the admin for each item in an order when the order status changes to Pending Payment.
Email sent when an order status is changed to Pending Payment.
A quick recap of which files do what:
- The email manager class queues up and triggers your emails to be sent by WooCommerce.
- The email class file adds your email in WooCommerce->Settings->Emails and also allows the user to easily manage the same.
- The email templates are used for creating the email content.
I have used this approach to create the emails that are sent by the Booking & Appointment Plugin for WooCommerce.
The plugin sends 4 different emails for different functionalities.
Originally I had 3 emails for the Requires Confirmation feature. Later when we decided to make the plugin compatible with 2 way Google Calendar sync, the need for another email template arose. That’s when I fully realized the ease of using WooCommerce to create our custom emails. All that I had to do was add an extra email class, create the templates and we were ready to go!
Once the email manager is setup, it’s just a matter of adding more email triggers, classes and templates. You can add as many custom emails as needed.
Do let me know in the comments if this post helps you create your custom emails the WooCommerce way!