Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Draft the marketplace message relay
Damian Legawiecef590ad4770a
diff --git a/docs/plans/6.1-marketplace-message-relay.md b/docs/plans/6.1-marketplace-message-relay.mdnew file mode 100644index 0000000000..a4647979ac--- /dev/null+++ b/docs/plans/6.1-marketplace-message-relay.md@@ -0,0 +1,144 @@+# Marketplace Message Relay++**Status:** Draft+**Target:** Spree 6.1+**Depends on:** `6.0-multi-vendor-marketplace.md`, `6.0-seller-product-submission.md`+**Author:** Damian Legawiec+**Last updated:** 2026-08-26++## Summary++A seller packs and posts a parcel, so they need a way to reach the buyer when+something goes wrong with the delivery. They do not need the buyer's email+address to do it — that is the one contact detail that lets a marketplace's+customer be taken off the marketplace, and Spree now withholds it from the+seller order (`6.0-seller-product-submission.md`).++Today that leaves the phone on the shipping address as the only contact route.+This plan adds the second: a relayed message between buyer and seller where+neither learns the other's real address.++Rails ships the machinery. Action Mailbox is already required by the starter+app and unused; `has_secure_token` is the same primitive Spree uses for cart+tokens, invitations and digital links.++## Why this is 6.1 and not 6.0++The blocker is not the code, it is the deployment contract. Outbound mail in+Spree is env-driven SMTP (`SMTP_ADDRESS`, `SMTP_USERNAME`, …), so it works on+any host that can open a socket. Inbound mail is not like that: relaying+requires a public endpoint that a provider can POST to, MX records pointed at+that provider, and provider-specific ingress credentials.++Shipping this in core would mean every Spree installation carries a feature+most of them cannot turn on. It belongs behind a deliberate opt-in, and 6.0 is+already carrying the marketplace core.++## Key Decisions (do not deviate without discussion)++1. **Neither party learns the other's address.** A relayed message is sent+ *from* a per-thread alias on the marketplace's own domain and *to* the+ real recipient. The reply comes back to the alias, which is what the+ inbound route resolves. Masking one direction only would be theatre.++2. **The alias is an opaque token, never a derived string.** A relay address+ built from an order number or a seller slug is guessable, and a guessed+ alias is an unsolicited-mail channel into somebody's inbox.+ `has_secure_token` on the thread, exactly as `Spree::DigitalLink` and+ `Spree::CompanyInvitation` do it.++3. **The thread is the unit, not the message.** One `Spree::MessageThread` per+ (order, seller) pair holds the alias and both participants; messages hang+ off it. A per-message alias would multiply the addresses a leak could+ expose and give the buyer a different reply-to every time.++4. **A thread is bound to an order and expires with it.** Relay is for+ "where is my parcel", not a general channel — it opens when the order is+ placed and closes a fixed window after the order is fulfilled or canceled.+ An alias that never expires is a permanent forwarding address to a+ customer's inbox.++5. **Inbound is provider-agnostic.** Action Mailbox's own ingresses+ (Mailgun, Mandrill, Postmark, SendGrid, and the generic `relay` for a+ self-hosted MTA) are the supported surface. Spree registers a mailbox and+ documents the ingress choice; it does not wrap or prefer one provider.++6. **The relay is optional and off by default.** A store preference, and an+ installation that has not configured inbound mail simply does not offer+ it — the seller order keeps the shipping phone it already has. Nothing in+ fulfillment may depend on the relay existing.++7. **Messages are stored, not merely forwarded.** The marketplace is the one+ who has to answer "what did the seller tell my customer" in a dispute.+ A forward-only relay leaves the operator with nothing to look at.++## Design Details++### Models++- `Spree::MessageThread` — `store_id`, `order_id`, `seller_id`, `token`+ (`has_secure_token`), `status` (`open` | `closed`), `closes_at`.+- `Spree::Message` — `message_thread_id`, `sender_type` (`customer` |+ `seller` | `operator`), `sender_id`, `body`, `delivered_at`.++Both `Spree::SingleStoreResource`. `status` is a plain `has_status`, moved by+workflows, per `6.0-service-workflows.md` — no state machine.++### Outbound++`Spree::MessageMailer` sends the body to the counterparty with+`reply_to: "#{thread.token}@#{store.preferred_relay_domain}"`. The `from` is+the marketplace's own address, as every other Spree email is.++### Inbound++`Spree::RelayMailbox` routes on the alias:++- resolve the thread by token; unknown or closed token is dropped, never+ bounced (a bounce confirms to a guesser which aliases exist)+- identify the sender by the envelope against the thread's two participants;+ a third party is dropped+- store the message, then mail the counterparty++### API and panel++- Seller branch: `GET /seller/orders/:id/messages`, `POST .../messages`.+- Store API: the customer's side, on their own order.+- Admin: read-only across threads, for disputes.++## Migration Path++1. Models + workflows + mailer (works without inbound: the marketplace can+ send, the reply just has nowhere to land).+2. `Spree::RelayMailbox` + ingress documentation.+3. Seller panel and storefront surfaces.+4. Operator's read-only view.++## Constraints on Current Work++- **Do not add the buyer's email back to any seller-facing serializer.** The+ relay is the replacement for it; putting the address back makes the relay+ pointless.+- **Nothing in fulfillment may require a thread to exist.** Relay is optional+ and a seller must be able to ship without it.+- A relay alias is never derived from anything guessable.++## Open Questions++- Whether the operator should be able to *post* into a thread or only read it.+ Reading covers disputes; posting makes the marketplace a party to the+ conversation, which may be what an operator wants and may be what they must+ avoid.+- Attachments. A delivery photograph is the obvious case and the obvious+ malware vector.+- Whether the storefront side is in scope for OSS at all, or whether a+ headless install is expected to render it from the API.++## References++- `docs/plans/6.0-seller-product-submission.md` — why the buyer's email left+ the seller order in the first place+- `docs/plans/6.0-multi-vendor-marketplace.md` — seller as merchant of record,+ which is why the seller keeps the addresses but not the inbox+- Rails Action Mailbox: `actionmailbox` ships Mailgun, Mandrill, Postmark,+ SendGrid and `relay` ingresses; the starter app already requires the engine