Customizing Email

Changing the appearance of email sent by Zen Cart

There are several places in the Zen Cart code where e-mails to the customer are constructed. To create a consistent feel for all your communication with the customer, you will want to make sure you modify all these places whenever you modify one.

Don’t forget to use the template overrides system wherever possible when making your changes and if this is not available look for notifiers and use the observer/notifier system to make your changes.

The e-mail’s structure is determined in one of two ways: if you are sending plain text e-mails, it is determined by the way you put together the various items (customer greeting, order number, link to detailed invoice, etc) in a string variable that is then passed to the zen_mail() function. If you are sending HTML e-mails, the structure is determined by the template you use.

Plain text e-mails

You can rearrange, add, or delete items in a plain text e-mail. To do so, you will need to either, use the template overrides system, the observer/notifier system or as a last resort edit the Zen Cart files where the e-mail is created. For example, if you want to edit the order confirmation e-mail, you will need to edit the file includes/classes/order.php.

In our example, we open up includes/classes/order.php and scroll down to the bottom of the file, in the function send_order_email(). There you will see the lines that construct the plain text e-mail message:

(line 1302)        $email_order = EMAIL_TEXT_HEADER . EMAIL_TEXT_FROM . STORE_NAME . "\n\n" .
                       $this->customer['firstname'] . ' ' . $this->customer['lastname'] . "\n\n" .
                       EMAIL_THANKS_FOR_SHOPPING . "\n" . EMAIL_DETAILS_FOLLOW . "\n" .
                       EMAIL_SEPARATOR . "\n" .
                       EMAIL_TEXT_ORDER_NUMBER . ' ' . $zf_insert_id . "\n" .
(line 1327)          $email_order .= zen_output_string_protected($this->info['comments']) . "\n\n";
(line 1334)        $email_order .= EMAIL_TEXT_PRODUCTS . "\n" .
                        EMAIL_SEPARATOR . "\n" .
                        $this->products_ordered .
                        EMAIL_SEPARATOR . "\n";

and so on. In this file, the variable that holds the plain text e-mail message is called $email_order; it generally has a different name in each file, such as $email or $email_text. Whatever its name, this is the place where you can make your changes, if you cannot use overrides or notifiers. You can add, delete, and rearrange the order of the items to suit your wishes.

Remember if you change core files you will have to do it for every upgrade.

If you don’t understand what’s going on in the lines above, you may want to Read more about PHP first.

HTML e-mails

The HTML e-mail templates are located in the folder email/ in your store’s root directory. There are several different templates, each for a different purpose. You can rearrange the items, add new items, or delete items to achieve the structure you want for your e-mails.

You need not edit any other Zen Cart files if you just want to rearrange or delete the items listed in an HTML template. To add items, however, you will need to find all the Zen Cart files that use that particular HTML template, and add in a definition for your new item. You can use the Developer’s Tool Kit. in the Admin to find all the files that use a given template; search for the last part of the template name. For example, if you want to add an item into the HTML template email_template_order_status.html, search for order_status using the Developer’s Tool Kit.

Once you have found the files that need to be edited, you will want to add a definition for your new HTML item to each one. For example, suppose you have added an item called $EMAIL_HOURS_OF_OPERATION to the email_template_order_status.html template. One of the files that you will need to edit is admin/orders.php. Find the part of that file where the e-mail message is being constructed; in this case, it begins around line 100.

You see that the HTML message is constructed with several statements like this:

      $html_msg['EMAIL_CUSTOMERS_NAME'] = $check_status->fields['customers_name'];

All you need to do is add a new statement under all these to define your new item:

      $html_msg['EMAIL_HOURS_OF_OPERATION'] = 'We are open from 9 AM to 5 PM every day of the week.';

Of course, it’s a better idea to use a constant instead of hardcoding your text like this, but we’ll do it like this in our example for clarity’s sake.

Use a $ in front of the name of your new item in the HTML template, but do not use the $ where you define it.

Finding files where e-mails are created

Here is a list to help you find the files you will need to edit to modify the structure of your e-mails.

Type of e-mail HTML template in folder email/ Search for this in Developer's Tool Kit
Contact Us email_template_contact_us.html 'contact_us'
Coupon email_template_coupon.html 'coupon'
Default email_template_default.html 'default'
Direct e-mail email_template_direct_email.html 'direct_email'
Gift Certificates email_template_gv_mail.html email_template_gv_send.html email_template_gv_queue.html 'gv_mail' 'gv_send' 'gv_queue'
Low stock email_template_low_stock.html 'low_stock'
Newsletters email_template_newsletters.html 'newsletters'
Order confirmation email_template_checkout.html 'checkout'
Order Status update email_template_order_status.html 'order_status'
Password forgotten email_template_password_forgotten.html 'password_forgotten'
Product notification email_template_product_notification.html 'product_notification'
Welcome email_template_welcome.html 'welcome'

Modifying the Order Confirmation email

A commonly requested change is adding a message to the email your customers get when they place an order. This is documented in How can I add a message to my order confirmation emails? .

Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified October 29, 2022 by brittainmark (2b7510c).