Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.md
new file mode 100644
index 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