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:
- Non-blocking, dependable delivery: since 1.7.0 emails go into BoxCart's own outbox and are sent once the page has answered, so sending never slows the request that triggers it, and a five-minute sweep sends anything left over.
- HTML email templates: All emails use responsive HTML templates with inline CSS, customisable colours, and optional logo branding.
- Mock data previews: Preview any email template in the admin with realistic mock order data before sending it to customers.
- Per-template control: Each email type can be individually enabled or disabled, and its subject, heading, and message body are fully editable.
Email settings are managed under BoxCart → Settings → Emails, which is divided into three sub-sections: Sender, Branding, and Templates.
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.
| Setting | Database Key | Default | Description |
|---|---|---|---|
| "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. |
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.
| Setting | Default | Description |
|---|---|---|
| How often | Weekly | Weekly (the 7 days before) on the day you choose, or Monthly, on the 1st (the month before). |
| Weekly on | Monday | The day a weekly report goes. Hidden when you choose monthly. |
| Send at | 08:00 | The time it goes, in your site's timezone. |
| Also send to | Blank | The 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:
- orders, revenue, average order and items, each compared with the period before;
- your best sellers;
- your busiest collection day and time, and with more than one location, your busiest collection point;
- cancelled orders, orders changed by their customers, and new customer accounts;
- with Search Insights on, what customers searched for: the number of searches, the most searched, the ones that found nothing, and searches that now find a product you've added;
- a warning if any order from the last week didn't send its shop email;
- a link to your reports.
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.
| Setting | Database Key | Default | Description |
|---|---|---|---|
| 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. |
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.
| Template | Template Key | Recipient | Default Subject | Description |
|---|---|---|---|---|
| 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:
- Subtotal and Discount, when there's a discount or VAT added on top
- VAT as its own line when it's added on top of your prices, or Includes VAT under the total when your prices include it (with Show tax breakdown on)
- Once money has moved since the order was placed (Pro): Paid, then Refunded to card, To give back at collection (part of a lower total that was paid in person) and To pay at collection (a paid order changed to cost more). Paid, less the money back, plus anything to pay, comes to the total (less any refund you chose to give).
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:
| Field | Database Key Pattern | Input Type | Description |
|---|---|---|---|
| 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. |
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.
| Placeholder | Replaced 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.
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:
- Your logo and branding colours
- The subject, heading, and message content
- Placeholder values replaced with sample data
- The complete email layout including header and footer
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.
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.
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
-
Event triggers an email
An action such as placing an order or changing an order status fires a WordPress hook (e.g.
boxcart_order_createdorboxcart_order_status_changed). -
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. -
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.
-
Email is dispatched
BoxCart_Email::process_queued_email()renders the HTML template, applies branding and placeholder values, and sends the email viawp_mail(). -
Anything left is swept up
Every five minutes the
boxcart_send_outboxcron 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.
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:
| Filter | Parameters | Description |
|---|---|---|
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.