Skip to content

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:

  1. 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 in web-mvc's view-resolver chain; the rest and worker Spring Boot apps depend on commerce-core only, so templateEngine.process("email/orderPlaced") simply could not find the template on those nodes.
  2. 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, #dates and, since Thymeleaf 3.1 integrated it into core, #temporals. No thymeleaf-extras-java8time dependency is needed.
  • #shopDates (ShopDatesDialect), for every date and time an email prints. #dates would print the worker's zone (UTC), an hour early for a UK shop in summer, so the renderer pins shopTimeZone to the zone of the site it renders for. See Dates and time zones.
  • The platform's site-aware MessageSource (BadgerMessageSource) for #{...} lookups, set via setTemplateEngineMessageSource(...). Because that message source reads the active site from TenantContext, the renderer sets TenantContext (and LocaleContextHolder) around every process() call and restores the previous values in finally, 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, formatted subject, from, to, bcc, locale, siteId, and an optional replyTo (an EmailAddressDto, null by default; the worker puts it on EmailRequest.replyTo and MailtrapEmailService sends it as reply_to). Jobs queued before replyTo existed carry none and still read.
  • Optional headers (a map, empty by default): extra message headers such as Message-ID, In-Reply-To and References on a contact request reply. The worker copies them to EmailRequest.headers, which MailtrapEmailService sends as the email's own headers. Jobs queued before headers existed carry none.
  • An EmailModelSpec describing 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.

Templates take the header logo from ${branding.logoUrl}, resolved by EmailBrandingService:

  1. the tenant's email-brand-logo-url config value (System > Site Config > email-branding), if set;
  2. 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's orderConfirmationFromAddress (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.uk default through Badger's account, as its other emails do.
  • In Badger's layout, never the shop's: templates live under templates/platform/email/ and EmailTemplateRenderer.renderPlatform reads them there. There's no branding or seller in the model.
  • In the shop's language, time zone and currency: the subject is a messages.properties key resolved in the shop's locale, and #shopMoney / #shopDates work 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, submitOrder pipeline)
  • Order dispatch (CustomerDispatchNotifier.notifyWholeOrderDispatch → OrderDispatchEmailSender), from the dispatchOrder pipeline 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, template orderPartialDispatched), 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 builds dOrder from only those lines, while order stays whole for the address and tracking. The order confirmation shows Ships to only when something on the order ships, and its status line comes from Order.confirmationStatusKey (see the order page)
  • Ready to collect (PickupServiceImpl.notifyReady, template orderReadyForCollection), 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's inline model as collectUrl. A collected order gets no dispatch or partial dispatch email (CustomerDispatchNotifier skips it)
  • Collection reminder (PickupServiceImpl.processHolds, from the worker's CollectionHoldJob, template orderCollectionReminder), once, a day before a ready order's hold ends, with the code and arrival link
  • Collected (PickupServiceImpl.recordCollected, template orderCollected), once, a short thank-you when the order is handed over
  • Newsletter confirmation (MarketingConfirmationEmail, from MarketingSignupServiceImpl, template marketingConfirm), 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's inline model (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, from ContactRequestInboxServiceImpl.reply, template contactRequestReply), when staff answer an enquiry from Customers > Contact requests. It is a SIMPLE job whose inline model carries shopName, replyBody (plain text: the template escapes it and keeps its line breaks), originalMessage and originalDate (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.enabled and the shop's inbound-email-replies-enabled, ContactRequestThreading), the job's replyTo is the conversation's r-<token>@<inbound domain> address, its headers carry Message-ID (kept on the stored message as providerMessageId), In-Reply-To and References (the conversation's earlier Message-IDs), the subject ends with the [#ABCD2345] reference, and replyAboveMarker puts 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 as replyTo; 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 from order.collectionOption(), never order.deliveryMethod (which is the delivery option on a split order), and list lines through DOrder helpers rather than dOrder.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, orderCollectionReminder and orderCollected list dOrder.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" from dOrder.deliveryProgress().
    • orderDispatched and orderPartialDispatched (with their -clean and -text variants) list dOrder.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's inline model, 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 -clean variants), orderTracking and orderCollected, HTML and text, carry Need help with this order? (email.common.needHelp / needHelpAt) under the order link, to the signed orderHelpUrl (/account/help/order/{token}, put on every ORDER-kind email's model by EmailJobModelReconstructor; /account/orders/{id}/help?from=email where 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 (SendPartCancellationEmailProcessor in the cancelOrderPart pipeline, template orderPartCancelled), 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. Follows order-cancellation-email-enabled; text from orderNotificationEmail.partCancelled*. See Order lifecycle
    • Items unavailable (ShortPickNotifier, template orderItemsUnavailable), 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) and FulfilmentServiceImpl (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 from email.shortPick.* (English and Spanish). See Items that can't be picked
  • Parcel tracking (TrackingServiceImpl → TrackingEmailSender, template orderTracking), once per parcel each, when the carrier reports it out for delivery, delivered or a problem, as the site's tracking-email-* settings allow. The carrier and tracking travel in the job's inline model. See Parcel Tracking
  • Order confirmation resend (OrderEmailResendServiceImpl.resendConfirmationEmail)
  • A till sale's receipt (PosReceiptServiceImpl, from POST /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, SIMPLE kind) — 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, template staffInvite, SIMPLE kind): 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 from EmailFulfilmentProcessor through the fulfiller's notifier; and OrderEmailResendServiceImpl.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, template giftAidChaser), sent from the worker's daily GiftAidChaserJob to 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, template customerService/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, template customerService/customerReplied), sent from the worker when a customer's email answer is added to a contact request: to the first matching customer-service-routing rule, else customer-service-notify-email (else the order notification address) and a copy to contact-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, SubscriptionEndingEmailListener for "will end" / "will continue", and CardRefusedEmailSender for "the card you chose can't be used", template subscriptionCardRefused) — straightforward to migrate via SIMPLE or a new Kind, 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 by ContactUsEmail for ContactUsExtension) goes to the shop in its email branding, with the stored contact request's id as its reference. What the sender typed is untrusted: ContactUsEmail strips control and bidi-override characters, keeps name, email and phone to one line and caps every field, and the template prints them only with th:text, never into a link, image or attribute. Replies go to the sender via Reply-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 the ReservationEvent that ReservationServiceImpl publishes in-process). These go through the email-jobs queue, so they get its retries and parking (see below): the listener queues an EmailJob (recipient, from, subject, and an EmailModelSpec of kind RESERVATION naming only the booking id and which email), and the worker's EmailJobListener rebuilds the model and the .ics from the booking as it then stands (ReservationEmailComposer, via EmailJobModelReconstructor), 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 under email/reservation/ sharing the layout in email/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 on email-jobs-dead-queue with 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.
Email 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 RepublishMessageRecoverer republishes the message to email-jobs-dead-queue (AMQPConfig.EMAIL_JOBS_DEAD_QUEUE) with the failure reason in the x-exception-message header.

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 SendingDomainService beside 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 variable bsite), 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: MailtrapWebhookService hands the bounces to TransactionalBounceService within the webhook request. Notifications are deleted by the usual retention job. Turn them off for a shop with supressedAdminNotifications=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 with supressedAdminNotifications=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:

  1. Decide a reconstruction strategy. If the model derives from a single Mongo document, add a new EmailModelSpec.Kind and the corresponding branch in EmailJobModelReconstructor.reconstructModel(...). If the model is genuinely primitive, use Kind.SIMPLE with the values in inline.
  2. At the trigger, resolve templateName, subject, from, to and bcc from site config (you still have the live SiteContext), build an EmailJob, and call emailJobPublisher.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's orderConfirmationFromAddress. Never default it to a @bdgr.co.uk address: a shop that sends through its own Mailtrap token can only send from its own domain, and Mailtrap rejects anything else with Unauthorized (DMRT's subscription cancellation emails failed this way until October 2026). The subscription and fundraiser emails all follow this rule.
  3. Add an activity entry if the trigger logs onto an order — record _QUEUED rather than _SENT, since the worker is now the one that actually sends.
  4. Add the template at commerce-core/src/main/resources/templates/shop/email/<name>.html, with an optional <name>-text.html. A Badger email goes in templates/platform/email/ and is rendered with renderPlatform.
  5. 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.