boxcart.dev

Emails

BoxCart includes a fully customisable email system with branded HTML templates, configurable sender details, and a non-blocking delivery queue powered by wp_cron.

Email System Overview

Every transactional email in BoxCart, from order confirmations to status updates, is rendered as a branded HTML email and delivered through a non-blocking queue. This means your customers receive professional, styled emails while your store's checkout performance is never impacted by email sending.

Key characteristics of the email system:

Email settings are managed under BoxCart → Settings → Emails, which is divided into three sub-sections: Sender, Branding, and Templates.

Email settings page showing sender, branding, and templates tabs

Sender Settings

The sender settings control who your emails appear to come from and where admin notifications are delivered. Configure these under BoxCart → Settings → Emails → Email Sender.

SettingDatabase KeyDefaultDescription
"From" Name email_from_name Your site name The name that appears in the "From" field of all outgoing emails.
"From" Email Address email_from_address WordPress admin email The email address used as the sender for all outgoing emails.
Admin Notification Email admin_email WordPress admin email The email address that receives admin notifications such as new order alerts and low stock warnings.
Email me the day's collections daily_collections_enabled, daily_collections_time, daily_collections_email Off, 07:00, blank Since 1.7.0: once a day at the time you choose (your site's timezone), BoxCart emails a list of that day's collections, grouped by collection point and then time: order number, customer name and item count, with totals and a link to that day's orders. Cancelled orders and card orders still waiting for payment are left out. The link opens the Orders screen on that day. On a day with none it sends "No collections today", so you always know it's working. It goes to the address you enter, or the admin notification email; HTML or plain text, following Admin Email Format. Send today's list now sends one straight away (it doesn't count as the day's email). It isn't a single cron job that could be skipped: the first visit after the chosen time, or BoxCart's five-minute email sweep on a quiet site, sends it once.
Email me a shop report (Pro) shop_report_enabled, shop_report_frequency, shop_report_day, shop_report_time, shop_report_recipients Off, weekly, Monday, 08:00, blank Since 1.8.0: a weekly or monthly summary of how the shop did. See Shop Report email.
Replies go to the customer admin_reply_to_customer On Since 1.7.0: the New Order, Order Modified, customer message and payment-failed emails to your shop are sent with the customer as their Reply-To, so pressing Reply answers the customer. Untick to have replies go to the sender address instead. A customer address that isn't a clean, valid email is skipped.
Tip

Use a dedicated email address for your store (e.g. orders@yourdomain.com) rather than a personal address. This helps with deliverability and makes it easier for customers to recognise your emails.

Shop Report email Pro

Since 1.8.0, BoxCart Pro can email you a short report on how the shop did, so you don't have to remember to open Reports. Turn it on under BoxCart → Settings → Emails → Email Sender with Email me a shop report.

Shop Report settings: Email me a shop report ticked, How often set to Weekly (the 7 days before), Weekly on Monday, Send at 08:00, Also send to, and a Send me the latest report now button
SettingDefaultDescription
How oftenWeeklyWeekly (the 7 days before) on the day you choose, or Monthly, on the 1st (the month before).
Weekly onMondayThe day a weekly report goes. Hidden when you choose monthly.
Send at08:00The time it goes, in your site's timezone.
Also send toBlankThe report always goes to the Admin Notification Email. Add up to five more addresses, separated by commas, such as a business partner or manager.

The report covers:

The subject line gives the period and the order count, for example "[Your Shop] Shop report, 26th Oct to 1st Nov: 23 orders". It follows your Admin Email Format (HTML or plain text), and the figures match Reports. Send me the latest report now sends the most recent report straight away, to you only, so you can see what it looks like.

Like the daily collections email, the report doesn't rely on a single cron job: the first visit after the chosen time, or BoxCart's five-minute email sweep, sends it once. On a quiet site it can go up to two days late rather than not at all. Switching the report on doesn't send one for a period that ended days ago.

Email Branding

Customise the visual appearance of your email templates to match your store's brand identity. These settings are found under BoxCart → Settings → Emails → Branding.

SettingDatabase KeyDefaultDescription
Email Logo email_logo_id None Upload a logo to display in the email header. Recommended size: 200px wide, PNG or JPG format.
Header Background Colour email_header_colour Falls back to primary colour The background colour of the email header area where the logo is displayed.
Accent Colour email_accent_colour Falls back to primary colour Used for buttons, links, and highlighted elements within the email body.
Footer Text Colour email_footer_colour #666666 The text colour used in the email footer area.
Footer Text email_footer_text Empty (uses default) Custom footer text displayed at the bottom of every email. Leave blank to use the default footer.
Email branding settings showing logo upload, header colour, accent colour, and footer text fields
Info

If you do not set the header background or accent colours, BoxCart will automatically use your store's primary colour from the Styling settings. This ensures visual consistency between your storefront and your emails.

Email Templates

BoxCart provides ten configurable email templates. Each template can be individually enabled or disabled and has editable subject lines, headings, and message content. Manage templates under BoxCart → Settings → Emails → Templates.

TemplateTemplate KeyRecipientDefault SubjectDescription
Order Confirmation order_confirmation Customer Order Confirmation - #{order_number} Sent to the customer immediately after a successful order (for a card payment, once Stripe confirms it). Includes order details, collection information, itemised list, payment info, and a link back to the order. On Pro, while a customer with an account can still change the order, the email says until when. Orders marked Completed as soon as they're placed (Auto-complete orders in Settings → Orders) get this email too, not the Completed one.
New Order (Admin) new_order_admin Admin New Order - #{order_number} Notifies the admin when a new order is placed. Layout (1.6.0): Full (the default) includes customer contact details, items with prices and totals, payment info, and a "View Order in Admin" button. Compact has just what you need to pack the order: order number, customer name, the customer's phone and email (since 1.7.0, as tap-to-call and email links in HTML), collection date and time, collection point, the items with how many there are (since 1.7.0), any customer notes, and an "Open the order" link. Both layouts come in HTML and plain text (see Admin Email Format under Sender Settings).
Status: Preparing status_processing Customer Order Update - #{order_number} Sent when the order status changes to "Preparing". Lets the customer know their order is being prepared.
Status: Ready for Collection status_ready Customer Order Ready for Collection - #{order_number} Sent when the order is ready to be collected. Includes collection location details and time slot.
Status: Completed status_completed Customer Order Completed - #{order_number} Sent when you mark an order completed after it has been collected.
Status: Cancelled status_cancelled Customer Order Cancelled - #{order_number} Sent when an order is cancelled, informing the customer of the cancellation. If you refunded their card payment (Pro), it says how much was refunded.
Order Modified (Customer) order_modified Customer — Sent to the customer when their order has been modified. If the change leaves something to pay at collection, it says how much. Uses template file order-modified.php.
Order Modified (Admin) order_modified_admin Admin — Sent to the admin when a customer modifies their order. Uses template file order-modified-admin.php (also has plain-text version).
Customer Message (Admin) order_message_to_admin Admin — Sent to the admin when a customer sends a message about their order. Uses template file order-message-to-admin.php (also has plain-text version).
Customer Message (Customer) order_message_to_customer Customer — Sent to the customer when the admin replies to their message. Uses template file order-message-to-customer.php.

Order totals in emails

Emails that list the order's items end with the same total lines as the order confirmation page and the admin order screen:

Whether VAT was included or added on top is read from the order's own amounts, so changing your tax settings later doesn't change old receipts.

Each template exposes the following editable fields:

FieldDatabase Key PatternInput TypeDescription
Enabled email_templates[{key}][enabled] Toggle Enable or disable this email. When disabled, the email will not be sent even when the trigger event occurs.
Subject email_templates[{key}][subject] Text The email subject line. Supports template placeholders.
Heading email_templates[{key}][heading] Text The main heading displayed at the top of the email body.
Message email_templates[{key}][message] Textarea The primary message body content shown beneath the heading.
Additional Text email_templates[{key}][additional_text] Textarea Extra text appended after the main content. Only available on templates that support it.
Layout email_templates[new_order_admin][layout] Select New Order (Admin) only: full (default) or compact. Added in 1.6.0.
Tip

You can reset any template back to its defaults using the reset button in the template editor. This is useful if you want to undo custom changes and start fresh.

The confirmation email's "What happens next?" text

By default the order confirmation ends with: "What happens next? We'll send you another email when your order is ready for collection. Please bring this email or your order number when you come to collect." If no such email will be sent, that promise wouldn't be kept, so since 1.6.0 the default text reads instead: "What happens next? There's nothing else you need to do. Please bring this email or your order number when you come to collect." That happens when the Status: Ready for Collection email is switched off, when the Ready status isn't used (Settings → Orders), or when orders are completed as soon as they're placed (Auto-complete orders, with order changes off). It switches back by itself when a Ready email will be sent again. Text you've written yourself is never changed.

System Emails

Alongside the editable templates above, BoxCart sends two system emails about payments: Payment Received, sent to the customer when you confirm a bank transfer, and Payment Failed, sent to you when a card payment fails. These are sent automatically by the plugin and are not editable templates, so they don't appear in the Templates list. Payment Received isn't sent when you confirm the balance on a part-paid order.

BoxCart Pro also sends you A refund didn't go through when a card refund fails at Stripe after it was made (since 1.8.0, see Failed refunds), and the Shop Report if you turn it on. Neither is an editable template.

Template Placeholders

BoxCart provides a set of merge tags (placeholders) that are dynamically replaced with real order data when the email is sent. You can use these placeholders in the subject, heading, message, and additional text fields of any template.

PlaceholderReplaced With
{customer_name} The customer's full name
{customer_first_name} The customer's first name only
{order_number} The order reference number (e.g. BC-1042)
{order_total} The formatted order total including currency symbol
{collection_date} The scheduled collection date
{collection_time} The selected collection time slot, in your site's time format (e.g. 2:00pm - 3:00pm, or 14:00 - 15:00 with a 24-hour clock)
{location_name} The name of the collection location
{site_name} Your WordPress site name

Example usage:

A subject line of Hi {customer_first_name}, your order #{order_number} is confirmed! would render as something like "Hi Sarah, your order #BC-1042 is confirmed!" when sent.

Info

Placeholders work in all editable text fields: subject, heading, message, and additional text. They are replaced at send time, so the preview feature will show them populated with mock data.

Preview and Testing

BoxCart includes built-in tools to preview and test your email templates before they reach your customers. These tools are accessible from the email template editor in BoxCart → Settings → Emails.

Live Email Preview

Each email template can be previewed in real time directly within the admin. The preview renders the full HTML email in an iframe, populated with realistic mock order data. This lets you see exactly how your emails will look to customers, including:

The preview opens in a new tab and uses your saved settings, so save your changes first. The one exception is the New Order (Admin) Layout: the preview and test email use the layout chosen on screen, so you can compare Full and Compact before saving.

Email template editor with live preview showing a branded order confirmation email

Send Test Email

To verify deliverability and rendering across email clients, you can send a test email to any address. Enter the recipient email address and click Send Test. The test email uses the same mock order data as the preview, giving you a realistic representation of what your customers will receive.

Tip

Send test emails to multiple email clients (Gmail, Outlook, Apple Mail) to check that your branding and layout render correctly across different platforms.

Email Queue

BoxCart uses a non-blocking email queue to ensure that email sending never slows down your store's checkout or admin operations. Understanding how the queue works can help you troubleshoot delivery issues.

How the Queue Works

  1. Event triggers an email

    An action such as placing an order or changing an order status fires a WordPress hook (e.g. boxcart_order_created or boxcart_order_status_changed).

  2. Email goes into the outbox

    BoxCart adds the email to its outbox: one row per email in the options table (names starting boxcart_outbox_, not autoloaded), so two things happening at once can't overwrite each other's emails.

  3. Sent once the page has answered

    At the end of the same request, after the response has gone to the visitor (with PHP-FPM or LiteSpeed the connection is closed first), BoxCart sends the email. Each one is claimed before sending, so it goes out once even if two requests try.

  4. Email is dispatched

    BoxCart_Email::process_queued_email() renders the HTML template, applies branding and placeholder values, and sends the email via wp_mail().

  5. Anything left is swept up

    Every five minutes the boxcart_send_outbox cron event sends any email that has waited over a minute (a request that ended before sending, say). A send that dies part-way is tried again after ten minutes, three times at most.

Info

Before 1.7.0 each email was a one-off WordPress cron event. WordPress keeps all cron events in one option, so on a busy moment (an order and a cron run at the same instant) an email could be lost. The outbox fixes that, and emails no longer wait for cron. Only the five-minute sweep uses cron: on a very quiet site, a system cron job calling wp-cron.php keeps that sweep on time.

Developer Filters

Developers can customise email behaviour using the following filters:

FilterParametersDescription
boxcart_email_recipient $to, $order Modify the recipient email address before sending.
boxcart_email_subject $subject, $template_type, $order Modify the email subject line.
boxcart_email_content $content, $template_type, $order Modify the rendered email content. Runs for the customer emails and, since 1.6.0, for the shop's own: new_order_admin, order_modified_admin, order_message_to_admin and payment_failed_admin. The shop's emails are plain text when Admin Email Format is Plain Text.
boxcart_order_email_changes_text $text, $order The line in the order confirmation email saying until when the customer can change the order (BoxCart Pro fills it in while changes are open; empty for none). Added in 1.6.0.
boxcart_email_headers $headers, $to, $subject Modify the email headers (e.g. add CC or BCC addresses).

See the Hooks & Filters reference for more details on using these filters in your custom code.