Addons by Reinos

Appearance

How does it work ​

Store Email takes over the emails of the Store module. It has no template tags of its own: whenever something happens to an order, it checks which of your email templates match the order and sends them. To understand where an email comes from (or why it doesn't arrive), see the steps below.

What changes in Store ​

When Store Email is installed:

  • Store doesn't send its own order confirmation email anymore. Not after the checkout, not when the payment provider completes the order and not with the resend button. Store's order confirmation template (Design → System Templates → Email) is no longer used. There is no fallback: when none of your templates match, no email is sent at all.
  • The Email section of the Store settings is hidden (Email from, Email from Name, BCC and Email type).
    • Email from and Email from Name are still used: you now edit them in the Settings of Store Email.
    • Store's BCC and Email type are not used anymore: every template has its own Bcc and Mail Type.
  • The resend button on an order in the Store CP now sends your matching templates again, see Resend.
  • Whether an email was sent or failed is written to the log of the order in the Store module.

Nothing else in Store changes: the Store menu stays the same, and the order, invoice and packing slip PDFs are still made by Store.

On install, two templates are created with the same subject and content as Store's order confirmation email, both sent to {customer_email}:

  • Order confirmation: when the order has status Complete and is paid.
  • Order confirmation (awaiting payment): when the order has status Pending and is not paid, e.g. an order with the Manual gateway (since Store 4.0.0 a new manual order gets the status Pending, or Complete when you choose that in the gateway settings) or a payment that is not confirmed yet.

So out of the box the customer gets an email for a paid order and for an order that waits for its payment, like Store sends it. An order that first waits for its payment gets the second email too once it is paid and Complete; disable or change one of the templates when you don't want that. These templates are only created on install: when you update from an older version, add a template on Pending + Is Paid No yourself (e.g. with the duplicate button) if you use the Manual gateway.

Uninstall ​

When you uninstall Store Email, all its templates, settings, logs and the "already sent" history are removed. Store then sends its own order confirmation email again and shows its Email settings again.

The flow ​

1. Something happens to an order ​

Store Email checks your templates when:

  • the checkout is finished (the customer returns from a completed payment, or places an order with a manual gateway);
  • the status, the paid state or the shipping status of an order changes, no matter who changed it: the customer, the payment provider, an admin in the CP or another add-on.

2. Which templates match? ​

All enabled templates of the current site are checked against the order as it is now (not against what just changed):

  • Trigger on (Status): the order has one of the selected statuses.
  • Trigger on (Is Paid): Yes = the order is paid, No = the order is not paid.
  • Trigger on (Is Shipped): Yes = the order is shipped, No = it is not. This follows {order:is_shipped}: the shipping status shipped or parcel_shipped, or what an add-on like MyParcel or Pickup decides.

A template matches when all triggers that are set match. Triggers left empty are ignored, but a template without any trigger is never sent. See When is an email sent?

Because the order is checked as it is now, a template with only "Is Paid Yes" is sent on the first change after the order is paid, whatever that change is.

3. Already sent? ​

Every template is sent only once per order. When it matches again later, it's skipped. When sending failed, it's tried again on the next change of that order. The resend button ignores this.

4. The email is built and sent ​

  • To: {customer_email} is replaced with the email address of the order, otherwise the fixed address is used.
  • Subject: the Template variables work, but no conditionals or tags.
  • From / From name: from the Settings. When one of them is empty, the webmaster email and name of ExpressionEngine are used (Settings → Outgoing Email).
  • Content: all order data and the other Template variables, conditionals, and normal ExpressionEngine tags and global variables. The email is not sent in the visitor's session, so member variables like {logged_in_member_id} are not the customer.
  • PDF attachments: with Include Confirmation PDF or Include Invoice PDF the same PDF as the download in the Store CP is attached.
  • The email is sent with the outgoing email settings of ExpressionEngine (Settings → Outgoing Email).

The email is sent in a separate request from your site to itself. An error while preparing or sending the email (template, PDF, email server) never breaks the checkout or the payment: the error is logged and the order continues. The checkout or payment does wait for that request, so a slow email server slows it down. It does mean that your server must be able to reach its own site URL, see Common pitfalls.

5. Logging ​

  • In the log of the order (Store module, see Store CP Overview): Successfully send email template ... or Failed to send email template .... This follows the Log setting of the Store module: a successful send is only logged when it's set to Everything.
  • In the Logging of Store Email: the reason why sending failed, depending on the Log setting.

Saving a template: the test order ​

When you save a template, its content is tested with a dummy order of Store (two products, not saved). If that fails, you get Your template could not be parsed. Please check your syntax and the template is not saved. This test also uses a request from your site to itself, so the error can also mean that this request failed, see Common pitfalls.

Resend ​

The resend button on an order in the Store CP (not shown for cancelled orders) sends all templates that match the order right now again, even when they were already sent. A template that doesn't match the current status, paid state or shipping status is not sent: to resend a "Complete" email, the order must still be complete.

Common pitfalls ​

No email at all

  • No template matches: check the triggers against the current status, paid state and shipping status of the order (all set triggers must match), and check that the template is enabled and belongs to the current site (MSM). Remember that Store doesn't send its own confirmation email anymore.
  • The template was already sent for this order (once per order); use the resend button.
  • The extension of Store Email is disabled (Add-Ons → Extensions) while the module is installed: Store doesn't send its own email and Store Email doesn't send anything either.
  • Nothing in the order log: a successful send is only logged when the Store Log setting is Everything. Check the Logging of Store Email for errors.

Sending fails, or "Your template could not be parsed" while the template is fine

Your server can't reach its own site. The Logging of Store Email shows the reason: allow_url_fopen is disabled, No response from the action URL (...) with the PHP error, or The action URL (...) redirects to .... The request waits at most 30 seconds. Check:

  • allow_url_fopen is enabled in PHP.
  • The server can reach its own site URL: DNS, firewall, a local or Docker setup, bot protection (e.g. Cloudflare) blocking server requests, or an invalid SSL certificate.
  • The site URL in ExpressionEngine doesn't redirect (http → https, www or not). Use the final URL as the site URL.
  • .htaccess password protection: when the payment provider completes the order, it has no password, so the email fails on a protected (staging) site.
  • The site is not offline (system off).

The email is logged as sent but doesn't arrive

  • "Sent" means the mail server (SMTP) or the mail program of the server (PHP mail / sendmail) accepted the email, not that it was delivered. When it is refused later (bounce, spam filter) it still counts as sent; use the resend button after fixing the problem.
  • When the mail server refuses the email right away, or the order has no email address, the email is logged as Failed to send email template ... with the reason in the Logging of Store Email. It is not tried again automatically, use the resend button.
  • Check the outgoing email settings of ExpressionEngine (SMTP), the spam folder and the From address: a From address on a domain your mail server isn't allowed to send for (SPF/DKIM) is often rejected or marked as spam.
  • The To field is {customer_email} and the order has a wrong email address.

Content or attachment problems

  • Variables with the order: prefix are not parsed: use {customer_first_name}, not {order:customer_first_name}.
  • The subject only gets variables, no conditionals or tags.
  • No PDF attached: the cache folder (system/user/cache/reinos_store_email/) must be writable. When the PDF can't be written, the email is sent without it and the error is logged in the log of the order and in the Logging of Store Email. The PDF layout and footer come from the PDF settings of Store.
  • The Bcc field accepts only one email address.