Transactional Email¶
How Badger Commerce renders and sends transactional emails (order confirmations, dispatches, gift cards, password resets, gift aid notifications, fundraiser updates, etc.) — the rendering engine, the worker offload for the high-volume flows, and the rules for adding a new email type.
Why this is its own subsystem¶
Email had two coupled problems that pulled it out of the request path:
- Templates need a resolver that works without a request. The email services ask for
email/orderPlaced(the name configured per site). Resolving that was historically only configured inweb-mvc's view-resolver chain; therestandworkerSpring Boot apps depend oncommerce-coreonly, sotemplateEngine.process("email/orderPlaced")simply could not find the template on those nodes. - Sending should not happen on request-handling threads. SMTP-bound work on the web/rest nodes adds tail latency to checkouts and POS submits, and a worker that can render emails independently lets the request nodes stay lightweight.
The result is a small renderer that works on any node, plus a RabbitMQ work queue that the worker drains.
The rendering engine: EmailTemplateRenderer¶
commerce-core/src/main/java/uk/co/kedos/badger/settbuilder/email/render/EmailTemplateRenderer.java
owns a privately-constructed SpringTemplateEngine. It is not a SpringTemplateEngine
bean — that would trip Spring Boot's @ConditionalOnMissingBean(SpringTemplateEngine.class)
and disable the auto-configured engine the web app uses to render pages. Keeping the email
engine private leaves the web view chain untouched.
The engine carries the minimum dialects email templates actually use:
- The Spring standard dialect (added automatically by
SpringTemplateEngine) —${...},#{...},#numbers,#strings,#lists,#datesand, since Thymeleaf 3.1 integrated it into core,#temporals. Nothymeleaf-extras-java8timedependency is needed. #shopDates(ShopDatesDialect), for every date and time an email prints.#dateswould print the worker's zone (UTC), an hour early for a UK shop in summer, so the renderer pinsshopTimeZoneto the zone of the site it renders for. See Dates and time zones.- The platform's site-aware
MessageSource(BadgerMessageSource) for#{...}lookups, set viasetTemplateEngineMessageSource(...). Because that message source reads the active site fromTenantContext, the renderer setsTenantContext(andLocaleContextHolder) around everyprocess()call and restores the previous values infinally, so it works equally on the web request thread and on the worker.
Two designs, no themes¶
Emails aren't themed: a shop's storefront theme has no effect on them. Every email template lives
in commerce-core/src/main/resources/templates/, in one of two designs:
| Design | Folder | Rendered by | Used for |
|---|---|---|---|
| Shop | templates/shop/email/ |
EmailTemplateRenderer.render(...) |
Everything sent on the shop's behalf: customers' emails and the shop staff's notifications, in the shop's branding (branding.* from EmailBrandingService) |
| Badger | templates/platform/email/ |
EmailTemplateRenderer.renderPlatform(...) |
Emails from Badger itself to the people who run a shop (see below) |
EmailDesignComplianceTest holds every template under either folder to its design: built on
email/layout :: page(...) or marked <!--/* partial: ... */-->, with no colour or font of its
own. The one exception is a standalone page the same renderer serves to a browser rather than an
inbox, marked <!--/* document: ... */--> (the printable fee invoice, platform/email/invoice/),
which carries its own styles.
Resolution is request-context-free. One EmailTemplateResolver maps the unprefixed name
(email/orderPlaced) into a design folder, picked by the emailDesign template resolution
attribute (shop or platform; shop when none is given). The renderer supplies that attribute
on every render call, so it never asks SiteContextProducer for anything. Template names stay
folder-relative (email/orderPlaced, email/layout), so a fragment reference inside a template
resolves within the same design. The attribute is part of Thymeleaf's cache key, so the two
designs never share cached templates (see Thymeleaf
#380).
The SiteContext the caller passes still matters: it sets the locale, messages, time zone and
currency the email renders in.
Attachments, streams and the text part¶
EmailRequest.attachments (file name to stream) are sent by MailtrapEmailService as base64
attachments, typed from the file name (.ics as text/calendar). EmailRequest.headers are sent
as the email's own headers (blank names or values left out).
Transactional email is one message per request on Mailtrap's transactional stream. Marketing
email never goes this way: email campaigns are sent one message per recipient
on Mailtrap's separate bulk stream (its own reputation and suppression list), through
MailtrapBulkProvider. The two can use different Mailtrap tokens: transactional mail uses the shop's
mailtrapApiKey, else the system key; campaigns use the account MailtrapAccountResolver picks
(see Your own Mailtrap account).
The plain-text variant (email/<name>-text) is optional — renderOptional returns null
if no -text template exists rather than throwing. MailtrapEmailService only sets the text
body when one was rendered.
The async offload: EmailJob queue¶
The order-pipeline emails publish a thin job to RabbitMQ; the worker consumes, rebuilds the template model from the IDs the job carries, renders via the engine above and sends.
+-------------+ publish +-----------------+ consume +-------------------+
| web/rest | ----------> | email-jobs- | ----------> | worker |
| pipeline | | queue (AMQP) | | EmailJobListener |
| step | +-----------------+ | |
| | | -> reconstruct |
| publishes | | -> render |
| EmailJob | | -> SMTP send |
+-------------+ +-------------------+
Wire format — IDs, never domain objects¶
EmailJob (in
commerce-core/.../email/queue/EmailJob.java) carries:
- Everything resolved from the request-scoped
SiteContext+ tenant config as plain strings:templateName, formattedsubject,from,to,bcc,locale,siteId, and an optionalreplyTo(anEmailAddressDto, null by default; the worker puts it onEmailRequest.replyToandMailtrapEmailServicesends it asreply_to). Jobs queued beforereplyToexisted carry none and still read. - Optional
headers(a map, empty by default): extra message headers such asMessage-ID,In-Reply-ToandReferenceson a contact request reply. The worker copies them toEmailRequest.headers, whichMailtrapEmailServicesends as the email's own headers. Jobs queued beforeheadersexisted carry none. - An
EmailModelSpecdescribing how to rebuild the template model on the worker, never the domain objects themselves.
public class EmailModelSpec {
public enum Kind { ORDER, ORDER_FULFILMENT, SUBSCRIPTION, RESERVATION, SIMPLE }
private Kind kind;
private String orderId; // ORDER, ORDER_FULFILMENT
private String reservationId; // RESERVATION (with reservationMessageKind)
private String fulfillerId; // ORDER_FULFILMENT
private Map<String, Object> inline; // SIMPLE + extras
}
That keeps the payload small, dodges fragile Jackson round-trips for Mongo documents, and
matches the existing event-listener pattern in the codebase (SubscriptionCancellationEmailListener,
FundraiserEventListener).
Reconstruction lives in commerce-core¶
EmailJobModelReconstructor (commerce-core) is what knows how to turn each Kind back into a
template model. The worker listener (worker/.../email/EmailJobListener.java) is a thin shell
that calls into it. Putting the reconstruction in commerce-core means each kind is unit-testable
without standing up the worker.
| Kind | Looks up | Adds to model |
|---|---|---|
ORDER |
OrderService.findOrder(orderId, site) + TicketDisplayService.forOrder(site, order) + AppointmentOrderDisplayService.forOrder(site, order) |
order, orderNumber, dOrder, appointments (paid appointments, empty for most orders: one card per LineItem.booking, read from the booking so Any available shows the practitioner actually given: type, day and time in the location's zone, address, the cancellation terms in words, and absolute links to manage or cancel (/booking/{token}) and add to a calendar (.ics, Google); orderPlaced shows them under the order summary, since a paid booking sends no email of its own), tickets (event tickets, empty for most orders; orderPlaced shows each with its QR as an absolute link to /o/{orderId}/{code}/tickets/{ticketId}.png (a hosted image, which shows inline where an attachment would not), plus the ticket's Apple and Google Wallet links when those are configured) |
ORDER_FULFILMENT |
OrderService.findOrder(orderId, site) + DisplayTools.constructFulfilmentDisplayOrder(..., fulfillerId) |
dOrder (filtered to that fulfiller), orderNumber, siteName |
RESERVATION |
ReservationService.find + ReservationEmailComposer |
the booking email's whole model (place, day, time, address, manage and confirm links, policy). EmailJobModelReconstructor.reconstructAttachments also rebuilds the .ics for the kinds that carry one, and recordSent logs the message on the booking once the provider accepts it |
SIMPLE |
nothing — inline-only | the inline map entries |
siteContext is always added; branding is added later by MailtrapEmailService from the
resolved site.
The email logo¶
Templates take the header logo from ${branding.logoUrl}, resolved by EmailBrandingService:
- the tenant's
email-brand-logo-urlconfig value (System > Site Config > email-branding), if set; - otherwise the storefront logo,
SiteContext.logoURL.
Either way the value is made absolute against the tenant's domainURL before it reaches the
template. This matters because SiteContext.logoURL is stored as a site-relative media path —
every web template renders it on the tenant's own domain, where the browser resolves it against
the current host. An email client has no such base, so a relative src renders as a broken image.
A value that cannot be made into something an email client will render — a relative path on a
tenant with no domainURL, or a non-http/data scheme — resolves to null rather than a broken
image, and templates fall back to a text heading of the site name. Absolute https:// and
http:// URLs are passed through untouched; a protocol-relative //host/path is given an
explicit https: scheme, since an email has no containing page for it to inherit one from.
Templates should therefore never reference ${siteContext.logoURL} directly.
The auth server's sign-in and confirmation-code email (AuthEmailService, its own template, not
the shop layout) takes its logo from the same place, EmailBrandingService.resolveLogoUrl.
Queue declaration¶
AMQPConfig.EMAIL_JOBS_QUEUE (email-jobs-queue) is declared durable and bound by name to
the AMQP default exchange — standard work-queue pattern, one consumer group (the worker).
EmailJobPublisher.publish uses rabbitTemplate.convertAndSend(EMAIL_JOBS_QUEUE, job).
Serialization is handled by the project-wide Jackson2JsonMessageConverter declared in
AMQPConfig.
Badger's own emails to shop staff¶
Most emails are the shop's: they go to its customers, in its email branding, from its
own address. A few are Badger's: Badger writes to the people who run the shop about something
it did for them: the Gift Aid claim accepted and claim not accepted emails, the
payout email, the monthly
fee invoice (FeeInvoiceServiceImpl, template
fees/invoice) and the welcome email a new self-serve shop's
owner gets once the shop is built (SignupProvisioningServiceImpl, template signup/welcome; see
Self-serve Sign-up).
PlatformEmailService (commerce-core) sends them:
- Named "Badger Commerce", from Badger's own address when one is set: the global setting
platform-email-from-address(System › Global config › email) names the address, and the email goes through the system Mailtrap account (system-mailtrap-api-key; a shop's own sandbox mode is ignored, only the stack-wide sandbox applies, as on the dev stack):EmailRequest.platformAccount. With the setting blank they go from the shop'sorderConfirmationFromAddress(e.g.Badger Commerce <[email protected]>) through the shop's own Mailtrap account and sandbox settings like any of its emails, so a shop pays for its own notifications; a shop with no Mailtrap account of its own then sends from the@bdgr.co.ukdefault through Badger's account, as its other emails do. - In Badger's layout, never the shop's: templates live under
templates/platform/email/andEmailTemplateRenderer.renderPlatformreads them there. There's nobrandingorsellerin the model. - In the shop's language, time zone and currency: the subject is a
messages.propertieskey resolved in the shop's locale, and#shopMoney/#shopDateswork as in any email.
platform/email/layout.html is the shared layout. An email fills its page(title, content,
badger, reason) fragment and builds its content from hero (label, figure, sentence), section
headings, rows with row / noteRow / referenceRow / totalRow, tiles of tile figures,
note and button. The From Badger panel (badger) sits below the
email's business, never above it; keep what it says true for every shop that gets it.
reason says why they got the email. The design decisions and the rules for a new one are in
Back-office emails.
What is async vs synchronous today¶
Phase 1 (the rendering engine) makes email rendering work identically on every node. Phase 2 (the queue offload) is opt-in per email type — we migrate flows that are genuinely fire-and-forget and leave interactive flows synchronous so they can give the user immediate sent/failed feedback. The current split:
Async via EmailJobPublisher → worker:
- Order confirmation (
SendOrderConfirmationEmail,submitOrderpipeline) - Order dispatch (
CustomerDispatchNotifier.notifyWholeOrderDispatch→OrderDispatchEmailSender), from thedispatchOrderpipeline or when the fulfilment roll-up completes the order; also the dispatch resend (OrderEmailResendServiceImpl.resendDispatchEmail) - Both dispatch emails list each item's own tracking (
LineItem.dispatchTracking) when the order has no order-level tracking, as on an order split between fulfillers - Partial dispatch (
CustomerDispatchNotifier.notifyPartialDispatch, templateorderPartialDispatched), when one fulfiller's part of a split order is finished - The dispatch, partial dispatch and parcel tracking emails list only what was sent (lines that
need shipping), not donations, tickets or digital products on the same order. A partial
dispatch lists just that fulfiller's parcel: the job carries its line ids
(
EmailModelSpec.lineItemIds) and the worker buildsdOrderfrom only those lines, whileorderstays whole for the address and tracking. The order confirmation shows Ships to only when something on the order ships, and its status line comes fromOrder.confirmationStatusKey(see the order page) - Ready to collect (
PickupServiceImpl.notifyReady, templateorderReadyForCollection), once, when a collection order is marked ready (admin, fulfiller portal or POS app). It shows the collection code and links to the arrival page; the link is minted when the job is queued and travels in the job'sinlinemodel ascollectUrl. A collected order gets no dispatch or partial dispatch email (CustomerDispatchNotifierskips it) - Collection reminder (
PickupServiceImpl.processHolds, from the worker'sCollectionHoldJob, templateorderCollectionReminder), once, a day before a ready order's hold ends, with the code and arrival link - Collected (
PickupServiceImpl.recordCollected, templateorderCollected), once, a short thank-you when the order is handed over - Newsletter confirmation (
MarketingConfirmationEmail, fromMarketingSignupServiceImpl, templatemarketingConfirm), when someone signs up on a form with double opt-in on. It carries a signed confirm link and an unsubscribe link in the job'sinlinemodel (confirmUrl,unsubscribeUrl), is sent at most once per address per 24 hours and goes out from the order-notification sender. Like the order emails it uses the customer email layout. See Customer Messaging and Consent - Contact request reply (
ContactRequestReplyEmail, fromContactRequestInboxServiceImpl.reply, templatecontactRequestReply), when staff answer an enquiry from Customers > Contact requests. It is aSIMPLEjob whoseinlinemodel carriesshopName,replyBody(plain text: the template escapes it and keeps its line breaks),originalMessageandoriginalDate(the request's date in the shop's zone, for "On ... you wrote:"). The subject is "Re: <their subject>", or "Your message to <shop>" when they gave none; the locale is the site default, because a request carries none. It goes out from the order-notification sender. With email replies on (badger.inbound-email.enabledand the shop'sinbound-email-replies-enabled,ContactRequestThreading), the job'sreplyTois the conversation'sr-<token>@<inbound domain>address, itsheaderscarryMessage-ID(kept on the stored message asproviderMessageId),In-Reply-ToandReferences(the conversation's earlier Message-IDs), the subject ends with the[#ABCD2345]reference, andreplyAboveMarkerputs the "Please type your reply above this line" line at the top, where quote stripping cuts the answer. With them off, when the Copy customer replies to setting (contact-request-reply-to) holds an address the job carries it asreplyTo; when it is blank there is no Reply-To header, so the customer's answer reaches the sender address. If the job can't be published the reply is still saved on the request, marked not sent. It uses the customer email layout, with the original message in a grey panel. See Customer Messaging and Consent - The order confirmation (
orderPlaced) of a collection order also prints the collection code. See Collecting an order - Split orders (some items collected, the rest delivered,
Order.isSplitHandover()). The templates read the store fromorder.collectionOption(), neverorder.deliveryMethod(which is the delivery option on a split order), and list lines throughDOrderhelpers rather thandOrder.lineItems:orderPlaced(HTML and text) shows a Collect from <store> section (address, instructions, slot or ready-from day, collection code, the collected items) and a Delivered to section (address, delivery option and promise, the delivered items), and its totals add Collection: Free above the delivery charge. Whole orders keep the old either/or block.orderReadyForCollection,orderCollectionReminderandorderCollectedlistdOrder.collectionLineItems(partLineIds)(on a split order, the collected items) and add "The rest of your order is being delivered separately / is on its way / has been delivered" fromdOrder.deliveryProgress().orderDispatchedandorderPartialDispatched(with their-cleanand-textvariants) listdOrder.deliveryLineItems(partLineIds)(on a split order, the delivered items) and say the collected items aren't in the parcel.partLineIds: when the sender puts a list of line ids in the job'sinlinemodel, a part email lists only those lines; without it the email lists every line (or, on a split order, its part's lines), so whole orders render exactly as before.- Text comes from
orderNotificationEmail.split.*keys. Render tests:SplitHandoverEmailRenderTest
- Help link.
orderPlaced,orderDispatched,orderPartialDispatched(and their-cleanvariants),orderTrackingandorderCollected, HTML and text, carry Need help with this order? (email.common.needHelp/needHelpAt) under the order link, to the signedorderHelpUrl(/account/help/order/{token}, put on everyORDER-kind email's model byEmailJobModelReconstructor;/account/orders/{id}/help?from=emailwhere it is absent, as in previews): the help form, which asks them to sign in first and attaches the order to the account of its email address.- Part cancelled (
SendPartCancellationEmailProcessorin thecancelOrderPartpipeline, templateorderPartCancelled), when one part of a split order is cancelled (by staff, or by the hold job when the collection isn't collected): lists that part's items and what was refunded. Followsorder-cancellation-email-enabled; text fromorderNotificationEmail.partCancelled*. See Order lifecycle - Items unavailable (
ShortPickNotifier, templateorderItemsUnavailable), when staff couldn't pick some items: one email for all of them, sent when the order is made ready or packed (or handed over or sent without that), whoever does it:PickupServiceImpl(notifyReady,recordCollected) andFulfilmentServiceImpl(lines packed or sent outside a pipeline) call it, and each short is marked told so it goes once. Also straight away for an item found short after that, or when the shorts left nothing and the order was cancelled (the cancellation email is then not sent too). Lists the items not coming, any picked in place of others ("2 x Cup, in place of Mug"), and those still coming, and says what was refunded, won't be charged (an authorised payment captured less) or will be handed back in cash. Always sent when the customer has an email address, since it is about their money. Text fromemail.shortPick.*(English and Spanish). See Items that can't be picked
- Part cancelled (
- Parcel tracking (
TrackingServiceImpl→TrackingEmailSender, templateorderTracking), once per parcel each, when the carrier reports it out for delivery, delivered or a problem, as the site'stracking-email-*settings allow. The carrier and tracking travel in the job'sinlinemodel. See Parcel Tracking - Order confirmation resend (
OrderEmailResendServiceImpl.resendConfirmationEmail) - A till sale's receipt (
PosReceiptServiceImpl, fromPOST /v1/pos/{locationId}/transactions/{orderId}/receipt): the order confirmation, to the sale's customer's own address, or the address the till entered for a walk-in; at most 3 a sale and 30 a member of staff an hour. See Mobile POS - Subscription dunning chaser (
SubscriptionDunningServiceImpl) - Password reset (
UserPasswordServiceImpl.sendPasswordResetEmail,SIMPLEkind) — the reset link is the only copy the user gets, so it must not be lost to a transient provider blip on a request thread - Staff invitation (
UserPasswordServiceImpl.sendStaffInvite, templatestaffInvite,SIMPLEkind): sent when POS staff makes an account for someone new; the same set-password link as a reset, valid for 7 days
Synchronous (rendered + sent on the calling node, all now working via the new renderer):
- Order fulfilment per-fulfiller (
EmailFulfilmentChannel, reached fromEmailFulfilmentProcessorthrough the fulfiller's notifier; andOrderEmailResendServiceImpl.resendFulfilmentEmail) — bespoke per-fulfiller filtering, follows the same pattern when migrated. - Gift-card delivery (
VirtualGiftCardFulfilmentProcessor) — carries a one-time plaintext PIN that is hashed and not stored, so reconstruct-from-IDs is impossible and the secret is deliberately kept off the queue (where the AMQP error handler would otherwise log failed payloads). - Gift Aid chaser (
GiftAidChaserServiceImpl, templategiftAidChaser), sent from the worker's dailyGiftAidChaserJobto donors who gave without Gift Aid, when the shop turns it on. The chaser record is written before the send and removed if the send fails, so a failed send is tried again the next day and a crash mid-send never emails a donor twice. See Gift Aid chaser email - Payout on its way (
PayoutNotificationServiceImpl, a Badger email), sent from the worker's Stripe webhook handler, whose retry covers a failed send - A customer conversation was assigned to you (
ContactRequestAssignmentService, a Badger email, templatecustomerService/requestAssigned), sent to the member of staff it was given to, unless they assigned it to themselves, with the customer, subject, topic and a link to the conversation - A customer replied (
ContactRequestReplyNotifier, a Badger email, templatecustomerService/customerReplied), sent from the worker when a customer's email answer is added to a contact request: to the first matchingcustomer-service-routingrule, elsecustomer-service-notify-email(else the order notification address) and a copy tocontact-request-reply-to, quoting the new text with a link to the conversation. Never for an auto-reply. The same notifier sends it when a customer answers in My account's Messages tab (from the web node), and, as "sent you a message" (newRequest, with the topic), when they start a conversation from the help form (CustomerHelpServiceImpl.start) - Gift Aid claim accepted and claim not accepted (
GiftAidNotificationService, both Badger emails; the second is sent once when a shop's claims start failing, see When a claim fails) and subscription cancellation (SubscriptionCancellationEmailListener,SubscriptionEndingEmailListenerfor "will end" / "will continue", andCardRefusedEmailSenderfor "the card you chose can't be used", templatesubscriptionCardRefused) — straightforward to migrate viaSIMPLEor a newKind, follow-up work. - Interactive flows that need immediate sent/failed feedback to a user:
Contact-Us (
ContactUsExtension: the enquiry is stored first, then the email sent), BillPay (BillPayAdminController) and the admin "send test email" (EmailBrandingController). - The contact form message (template
contactUsReceived, built byContactUsEmailforContactUsExtension) goes to the shop in its email branding, with the stored contact request's id as its reference. What the sender typed is untrusted:ContactUsEmailstrips control and bidi-override characters, keeps name, email and phone to one line and caps every field, and the template prints them only withth:text, never into a link, image or attribute. Replies go to the sender viaReply-To(EmailRequest.replyTo), set only when their address is valid; the email says so when it isn't. - Fundraiser emails (
FundraiserEventListener) — already on the worker via the existing fundraiser events queue; the new renderer fixed a latent rendering issue there. - Table booking emails (
ReservationEmailListener, on theReservationEventthatReservationServiceImplpublishes in-process). These go through the email-jobs queue, so they get its retries and parking (see below): the listener queues anEmailJob(recipient, from, subject, and anEmailModelSpecof kindRESERVATIONnaming only the booking id and which email), and the worker'sEmailJobListenerrebuilds the model and the.icsfrom the booking as it then stands (ReservationEmailComposer, viaEmailJobModelReconstructor), sends, and only then logs the message on the booking. Naming the booking, rather than shipping the model and the calendar, keeps the guest's details, the signed manage link and the file bodies off the queue, and means a retry minutes later still describes the booking correctly. Each has its own template underemail/reservation/sharing the layout inemail/reservation/parts. Every one shows the restaurant's name, address, phone and a Google Maps directions link, the booking's day, time, party size, occasion and reference, and (while the booking is upcoming) a freshly signed manage-booking link (ReservationLinks); the booking ones add the dining room's policy (how long a table is held, how many hours before to cancel). Each email the provider accepted is logged on the booking (Reservation.messages); one that fails is retried, then parked onemail-jobs-dead-queuewith no log entry. A reminder (or cancellation) whose booking is gone by the time the worker gets to it is dropped, since a reminder for a cancelled booking would only confuse the guest.
| Sent when | Template | .ics |
|
|---|---|---|---|
| Confirmation | a table is booked (online, by phone) | confirmation |
the event |
| Request received | a party over the instant-book size asks for a table | enquiryReceived |
none |
| Request approved | staff approve it (approveEnquiry) |
enquiryApproved |
the event |
| Request declined | staff decline it (declineEnquiry) |
enquiryDeclined |
none |
| Change | the time, party size, occasion or request changed (amend) |
amendment |
the same event, updated |
| Cancellation | the guest or the restaurant cancels (worded for each) | cancellation |
cancels the event, if it ever held a table |
| Reminder | the day before, from the site's dining-reminder-hour (16:00 by default, the location's time), sent by the worker's ReservationReminderJob through ReservationService.remind |
reminder |
none |
| Pay for your appointment | staff book a paid appointment by phone with a payment link, or resend it (BookingPaymentRequestService, through ReservationEmailListener.queue, not an event). Shows the price, the cancellation terms, a Pay and book button to /pay/{token} and when the time is held until; a retry after the request was paid, withdrawn or freed shows no button |
paymentRequest |
none |
There is no no-show email: a no-show is marked by staff and costs nothing until phase 3. The
reminder carries a "Yes, we're still coming" button (ReservationLinks.confirmUrl, the manage
page with ?confirm=1, where the guest presses confirm; opening the link confirms nothing, as
mail scanners open links). Bookings made on the day, or the day before after the reminder hour,
get no reminder. remind claims the booking (remindedFor) on the stored document before
publishing, so several workers send each reminder once, and a booking moved to another day is
reminded again. If the reminder then can't be queued (RabbitMQ unreachable),
ReservationService.releaseReminder clears the claim so the next 15-minute run tries again; once
it is queued the claim stands and the queue's retries take over, so a provider's "too many emails"
no longer loses it.
The .ics (ReservationCalendar) uses UTC times, which are exact either side of a clock change
and need no VTIMEZONE; one UID per booking with SEQUENCE from its version, so a change or
cancellation replaces the event the guest added; and METHOD:PUBLISH (with STATUS:CANCELLED
for a cancellation) rather than a meeting invitation. It names the place, the party size and the
reference, never the guest, and never the manage link (calendars get shared). The manage page's
"Add to calendar" downloads the same file from the same class, so the guest ends up with one
event whichever they use.
The auth server's AuthEmailService references templates by their fully-qualified path
(auth/email/...) and is intentionally outside this subsystem.
Delivery failures: bounded retry, then parked¶
EmailJobListener throws on any job it cannot deliver — a provider rejection, a null
response, a malformed job, an unresolvable site, a model it cannot reconstruct. Throwing is what
hands the message to the listener container's retry advice; acking (which this used to do) would
lose the email.
The listener runs on its own container factory, emailJobsListenerContainerFactory, not the
shared rabbitListenerContainerFactory — a retry chain on the shared factory would change
redelivery behaviour for every listener in the platform at once. It is configured with:
- Bounded retry —
AMQPConfig.EMAIL_JOB_MAX_RETRIES(3) retries after the first attempt, starting at 2s and tripling, capped at 20s. - A parking queue — once attempts are exhausted, a
RepublishMessageRecovererrepublishes the message toemail-jobs-dead-queue(AMQPConfig.EMAIL_JOBS_DEAD_QUEUE) with the failure reason in thex-exception-messageheader.
email-jobs-dead-queue is a separate queue, not an x-dead-letter-exchange argument on
email-jobs-queue. RabbitMQ queue arguments are immutable, so a broker-level DLQ would have meant
draining and recreating the live queue; republishing from the application achieves the same
outcome with no change to the existing queue.
Nothing consumes the parking queue
Parked jobs accumulate in email-jobs-dead-queue until someone looks at them in the RabbitMQ
console. This turns silent loss into silent parking — which is strictly better, but an
alert on queue depth (or a small admin view) is still needed before anyone reliably finds out
that a customer's email never arrived. Treat a non-zero depth as a bug, not a backlog.
Why permanent failures are retried too¶
EmailSendFailedException carries a permanent flag — set for a 4xx from the provider (except
408 and 429), a malformed job, or an unresolvable site — but it is diagnostic only and does not
suppress retries. This is deliberate and easy to "optimise" wrongly: the retry policy is the
only thing that invokes the recoverer, so an exception the policy declines to retry is not
parked. It falls through to ConditionalRejectingErrorHandler, which either discards it outright
or nacks it with requeue and hot-loops. Retrying a doomed job three times costs seconds; skipping
the retry loses the message or spins forever.
Note the classification is only as good as the provider's reporting: MailtrapEmailService only
ever reports 400 or 500, and its 500 covers both a provider outage and a missing API key.
Bounced emails: an admin notification¶
The retry and parking above cover emails Badger couldn't hand to Mailtrap. An email Mailtrap accepted
can still fail to arrive: the address was mistyped ([email protected], whose domain has no mail
server), the mailbox doesn't exist, or Mailtrap refused to send it because the address is on its
suppression list. Shop staff are told about these on the admin Alerts page (/admin/events), as
an "Email to … bounced" notification. It links to the customer whose contact or sign-in email it is,
and to the newest order with that checkout email, so staff can check the address with the customer
and correct it.
- Where it comes from. A second Mailtrap webhook, on the transactional stream, made by
SendingDomainServicebeside the campaign webhook once the shop's sending domain is verified (Customers, Sending domain). It reports only bounces, soft bounces and rejects, to the same URL, signed with its own secret (transactional-webhook-signing-secret). In the shop's own Mailtrap account it covers every domain the shop sends from (order emails usually come from the main domain, campaigns from a subdomain); in Badger's account, which other shops share, only the shop's sending domain. Every transactional email names the shop that sent it (Mailtrap custom variablebsite), so an account shared by two shops reports each bounce to the right one. A shop without a verified sending domain gets no bounce notifications. A domain verified before this webhook existed gets it on its next scheduled check (daily once the domain is a week old). - What's notified. Hard bounces and rejects always. A soft bounce only when its category means it won't come right on its own (DNS failure, bad domain or mailbox, inactive mailbox, given up): a full mailbox or a busy server usually delivers on retry. One notification per message, however many times Mailtrap reports it.
- Personal data. The address is shown on the notification (as on the "order placed" one) and
is kept only there. It is never logged or queued:
MailtrapWebhookServicehands the bounces toTransactionalBounceServicewithin the webhook request. Notifications are deleted by the usual retention job. Turn them off for a shop withsupressedAdminNotifications=emailBouncedEvent.
Subscription emails go to the customer's current address, not the one on the sign-up order (see Subscriptions), so correcting the customer's contact email is enough for the next subscription email to arrive.
Emails the provider refuses: an incident alert¶
When Mailtrap refuses to send for a shop, every email of that shop fails until someone puts the
account right, and the failed email can't be the thing that says so. EmailSendFailureAlerter
(called by MailtrapEmailService on every send) reports it as an incident:
- Opens on the first refused email, when Mailtrap rejects the API key (
Unauthorized, which is also its answer when the sender address isn't on a domain the account may send from), when no API key is set at all, or when the account has reached its daily sending limit. - Stays quiet while it is open, however many emails fail.
- Closes on the shop's next email that Mailtrap accepts, and says how long sending was failing.
Who is told:
- Badger, in Slack (
#badger-notifications), on opening and on closing, naming the shop and whether the email went through the shop's own Mailtrap account or Badger's. - The shop's staff, on the admin Alerts page (
/admin/events), when the shop sends through its own Mailtrap account (mailtrapApiKey) and so can fix it: "Your shop's emails aren't being sent", then "Your shop's emails are being sent again" (EmailSendingFailedEventBean,admin/events/emailSendingFailed.html). A fault in Badger's account is Badger's to fix, so the shop isn't alerted. Turn these off for a shop withsupressedAdminNotifications=emailSendingFailedEvent.
The open incident is a Redis key per shop and account (email-send-incident:<siteId>:<own|badger>),
shared by every node, kept 30 days: a shop still failing after that is reported afresh on its next
refused email. With Redis down nothing is reported and the send itself is unaffected. Other
failures (a timeout, a Mailtrap outage) are retried by the email queue and aren't reported here.
Refused emails are not re-sent when the incident closes: re-send them from the order.
Adding a new transactional email¶
For a fire-and-forget email that should run on the worker:
- Decide a reconstruction strategy. If the model derives from a single Mongo document,
add a new
EmailModelSpec.Kindand the corresponding branch inEmailJobModelReconstructor.reconstructModel(...). If the model is genuinely primitive, useKind.SIMPLEwith the values ininline. - At the trigger, resolve
templateName,subject,from,toandbccfrom site config (you still have the liveSiteContext), build anEmailJob, and callemailJobPublisher.publish(job). Do not put domain objects into the model. Send from the shop's address: give the email's own from-address key no default and fall back to the shop'sorderConfirmationFromAddress. Never default it to a@bdgr.co.ukaddress: a shop that sends through its own Mailtrap token can only send from its own domain, and Mailtrap rejects anything else withUnauthorized(DMRT's subscription cancellation emails failed this way until October 2026). The subscription and fundraiser emails all follow this rule. - Add an activity entry if the trigger logs onto an order — record
_QUEUEDrather than_SENT, since the worker is now the one that actually sends. - Add the template at
commerce-core/src/main/resources/templates/shop/email/<name>.html, with an optional<name>-text.html. A Badger email goes intemplates/platform/email/and is rendered withrenderPlatform. - The renderer is automatic — no engine wiring needed.
For an interactive email that needs synchronous sent/failed feedback, keep calling
emailService.sendEmail(...) on the calling node; rendering on that node now works because
of EmailTemplateRenderer.