Extend the account email-preference center to event, Slack, and newsletter purposes

[alexeygrigorev]

Parent decision: #22
Related: #21, #50, #225

Context

Decision #11 (resolved in #22) authorizes the email-purpose catalog. Recipients control optional
mail through the existing account-settings preference mechanism; this issue extends that mechanism
and the Relay delivery checks rather than introducing a second preference system.

Product contract

Preference categories

• Event email is optional and applies only to a recipient registered for the relevant event. The
  recipient may opt out of all event mail, including verification, confirmation, cancellation,
  reschedule, reminder, and other event-lifecycle messages. Event preference is separate from
  newsletter/marketing preference.
• Marketing/newsletter is a separate optional category. New member/account signup defaults it on,
  but an unverified new account is not a newsletter recipient. The recipient can unsubscribe later.
• Slack access is a one-time requested-service message, not a recurring preference category. It has
  no preference toggle and is not sent again automatically. Account verification and password
  recovery are also non-optional security messages.

Audiences and onboarding

• A new account receives email verification first. After successful verification, it receives one
  Slack join-link email, and the current link is also available in the authenticated member area.
• Legacy/imported contacts bypass the new-account verification-to-Slack sequence and do not receive
  an automatic Slack message merely because they were imported.
• Newsletter delivery targets verified contacts plus the explicit legacy/imported audience, which is
  treated as assumed verified for newsletter delivery. A new account must verify before entering the
  verified audience.
• An identifiable logged-in interaction or a recipient-specific newsletter-link interaction may
  move a legacy contact from legacy to verified. This is not a newsletter delivery prerequisite
  and does not trigger another email. A bare anonymous visit does not identify a contact and does
  not change status.

Mailchimp reconciliation

Mailchimp is authoritative for legacy marketing subscription state. Provide two separate,
idempotent import operations:

• subscribed list: turn the matched legacy marketing preference on;
• unsubscribed list: turn the matched marketing preference off.

The operations affect only the marketing/newsletter preference. A contact absent from both lists
keeps the current platform preference. The supported input lists are assumed clean and mutually
exclusive; overlap precedence is out of scope.

Unsubscribe and link safety

• A visible body/footer unsubscribe link opens the website preference page. The recipient unticks
  unwanted categories and submits; the initial GET is non-mutating.
• A supported Gmail/email-header one-click action may immediately and idempotently disable only the
  category represented by that message, without changing unrelated categories.
• Preference and newsletter-attribution links use opaque, recipient- and purpose-scoped, expiring,
  replay-safe tokens. Raw email addresses never appear in URLs or logs. A newsletter token is for
  recipient attribution and legacy-status promotion, not an additional verification gate.

Ask

Extend the existing preference-toggle mechanism and shared application services to add event and
marketing/newsletter categories, enforce them before Relay submission, support the preference-center
unsubscribe flow plus the email-header one-click path, and add the two Mailchimp legacy preference
imports. Do not add a recurring Slack toggle or a separate preference implementation.

Acceptance criteria

• Existing account settings exposes event and marketing/newsletter preferences without creating
  a parallel toggle system; existing course categories remain unchanged.
• Event mail is sent only to an active registrant for the relevant event and only while the
  event preference is enabled. Opting out suppresses every event-lifecycle message.
• Marketing/newsletter sends are made only to verified contacts and the explicit legacy audience;
  unverified new accounts are excluded.
• Preference state is enforced before Relay submission, with idempotent suppression and no
  changes to unrelated categories.
• A body/footer unsubscribe link opens the preference page, where the recipient can untick
  categories and submit; the initial GET does not mutate state.
• The supported email-header one-click action disables only the represented optional category,
  immediately and idempotently.
• New signup sends verification before the one-time Slack join-link delivery; the link is also
  available in the authenticated member area, and retries do not create automatic duplicates.
• Legacy/imported contacts bypass the new-signup sequence; identifiable account/newsletter
  interactions may promote legacy to verified, while anonymous visits do not.
• Subscribed and unsubscribed Mailchimp imports independently turn the legacy marketing
  preference on/off; absent contacts preserve the current platform preference. List overlap is
  outside the supported input contract.
• Preference/attribution tokens are opaque, scoped, expiring, replay-safe, redacted, and never
  expose raw email addresses in URLs or logs.
• All email mutations use the existing application services, one durable EmailDelivery intent
  and after-commit job, Relay routing, and the established idempotency/reconciliation model.

Dependencies

Depends on #22 (resolved). Coordinates with #21/#50 for Relay purpose/template identifiers and with
#225 for the shared preference-center surface (GA4 remains a separate purpose).

[alexeygrigorev]

PM readiness audit — issue #227 (2026-08-27)

Disposition: NOT READY for engineering; normative email-policy reconciliation is required first.

The issue is directionally groomed, but its source-of-truth documents currently disagree:

• _docs/specs/open-decisions.md §11 records the 2026-08-26 owner override that
  marketing/newsletters are in scope and tracks this extension in Extend the account email-preference center to event, Slack, and newsletter purposes #227;
• _docs/specs/05-events-registration-email.md still says marketing campaigns/newsletters are
  out of MVP scope and that non-course purposes fail closed until Decision: Confirm the MVP transactional email purpose catalog #22 approval; and
• the closed Decision: Confirm the MVP transactional email purpose catalog #22 issue body still says marketing/newsletters remain deferred, which conflicts with
  the later decision-record override.

Before engineering starts, the product owner/spec owner must reconcile those authoritative texts
and confirm the intended #227 contract: which event/Slack/lifecycle messages are opt-out eligible,
which transactional messages remain mandatory, how newsletter unsubscribe tokens are scoped,
revoked, expired, redacted, and replay-safe, and which Relay purpose identifiers are used. The
updated contract must preserve separate optional marketing consent and the unified retention/
privacy rules.

#227 also remains dependent on the open Relay lifecycle/purpose work in #21 and #50. No source
change, preference toggle, send path, provider call, or production configuration is authorized
from this issue until those gates are clear.

[alexeygrigorev]

PM owner-decision packet — 2026-08-27

The current specs now contain the resolved #22/#23 direction, but specification 05 still has the
older “marketing/newsletters out of MVP” paragraph. Before engineering, the product/spec owner
should reconcile that paragraph and record the following concrete contract (or an explicit change):

Proposed purpose and preference boundary

• Mandatory transactional messages: account verification/password recovery; event email
  verification, registration confirmation, cancellation, reschedule, and other messages required
  to complete or materially change an active registration; course/account lifecycle messages
  required by an action; and the requested Slack-access delivery. These cannot be suppressed by an
  optional preference.
• Optional categories: event announcements/updates not required to complete or change an
  active registration, and marketing/newsletter mail. Marketing consent remains separate from
  other preferences. If Slack access is intended to be optional rather than requested-service
  transactional mail, that must be stated explicitly; the current issue cannot safely treat both
  meanings as one toggle.
• Each Relay purpose ID must map to exactly one preference category or to an explicit mandatory
  class. A purpose-level toggle must not accidentally suppress a required message that shares its
  trigger family.

Unsubscribe contract

For optional marketing/newsletter mail, use an opaque, hashed, recipient- and purpose-scoped token
bound to the current account/consent revision. It must be single-use or replay-idempotent, expire,
be revocable on account deletion/consent reset, avoid email/address data in the URL, produce no
observable account enumeration, and record only redacted audit metadata. The email one-click path
must be safe for automated link scanners and must not send mail or change unrelated preferences;
the final GET/POST confirmation shape and Relay List-Unsubscribe purpose identifier need owner
approval.

Required source reconciliation

Update specification 05 to remove the obsolete marketing deferral, identify the mandatory versus
optional event/Slack/lifecycle classes above, and reference the unified retention/erasure policy
from #23. Then pin the resulting Relay purpose IDs and preference semantics in #21/#50/#227.

Until that owner/spec decision is recorded, #227 remains not ready for engineering. No
preference toggle, unsubscribe endpoint, provider call, source-spec edit, or production
configuration is authorized by this packet.

[alexeygrigorev]

Owner decision 1 — Slack email semantics — 2026-08-27

The Slack-access message is a one-time requested-service email: it is the first email the member receives for that access flow, is mandatory transactional delivery, and is not sent again automatically. It is not an optional recurring preference category. Any implementation must preserve idempotency and avoid duplicate delivery on retries.

The #227 acceptance wording that asks for a Slack opt-out toggle is superseded by this decision and must be removed during re-grooming. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 2 — Event email semantics — 2026-08-27

Event email is an optional category. Messages are sent only to a recipient who signed up for the relevant event; there is no event email to non-registrants. A recipient may opt out of all event email, including verification, registration confirmation, cancellation, reschedule, and other event lifecycle messages.

This supersedes the prior draft wording that treated event lifecycle messages as non-optional. The implementation must enforce the preference before sending and make the no-email consequence clear in the registration flow. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 3 — Marketing/newsletter default — 2026-08-27

Assuming “sign up” means member/account signup: marketing/newsletter delivery is enabled by default when the account is created. The recipient can unsubscribe at any time, and an unsubscribe must suppress future marketing/newsletter sends.

Marketing/newsletter remains a distinct preference purpose from event and Slack delivery. This supersedes the earlier proposed explicit-opt-in wording. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 4 — Verification before Slack access — 2026-08-27

Account signup sends an email-verification message first. After the recipient successfully verifies email ownership, the system sends the one-time Slack join-link email. The Slack link is not sent before verification and is not sent repeatedly automatically.

This clarifies and supersedes the earlier shorthand about the Slack message being the first email: verification is the first signup email; Slack access follows verification. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 5 — Legacy/imported contacts — 2026-08-27

The email-verification → Slack-join sequence applies only to new account signups. Legacy/imported contacts do not need that sequence, and the system must not replay verification or automatically send a Slack join-link email to them merely because they were imported. Any later communication or access action for those contacts follows its own explicit, provenance-aware flow. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 6 — Legacy recipients and verification — 2026-08-27

For the relevant email audience, send to verified recipients plus the explicit legacy/imported-contact audience. Legacy/imported contacts do not need the new-signup verification → Slack sequence. A qualifying website/email interaction may promote a legacy contact to verified.

The exact qualifying interaction remains to be pinned down: an ordinary anonymous page visit or an automated email-link scanner must not be treated as proof of inbox ownership without an explicit product/security rule. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 7 — Legacy marketing preference import — 2026-08-27

The uploaded Mailchimp list of people who are still subscribers is the authority for the initial marketing/newsletter toggle on legacy accounts. A legacy account matched to that active-subscriber list starts with marketing enabled; every other legacy account starts with marketing disabled, even if the person is still taking courses. Course participation does not infer email subscription.

New account signup remains default-on as decided above, with unsubscribe available. The legacy import must preserve the distinction between marketing preference and course participation/verification state. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 8 — Mailchimp-compatible unsubscribe flow — 2026-08-27

Match Mailchimp’s current behavior:

• The visible unsubscribe link in the email body/footer opens an unsubscribe page; the recipient confirms with a second “Unsubscribe” action before the marketing toggle changes.
• Supported email clients also receive a one-click unsubscribe capability through the email headers.
• The initial body-link GET is non-mutating and the final unsubscribe action is idempotent.

Reference: Mailchimp — About Unsubscribes and Add an Unsubscribe Link. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 9 — Legacy verification trigger — 2026-08-27

Use the second option: a legacy/imported contact becomes email-verified when they click a signed link addressed to that contact. No second confirmation screen is required. A normal anonymous website visit does not verify anyone.

The signed link must remain opaque, purpose-bound, expiring, and replay-safe. This intentionally accepts the risk that an inbox security scanner could follow the link and trigger verification; the product owner chose the lower-friction click-only behavior. No code or provider configuration was changed.

[alexeygrigorev]

Correction to decision interpretation — 2026-08-27

I misinterpreted the owner’s “I think it’s second” response. It refers to the unsubscribe options: confirmation first, matching the Mailchimp-compatible two-click body/footer flow already recorded in decision 8.

It does not decide the separate legacy-contact verification trigger. The earlier decision-9 comment should be disregarded; signed-link-only verification versus explicit confirmation remains open. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 10 — Preference-center unsubscribe behavior — 2026-08-27

Clarification to the earlier unsubscribe notes: use a Mailchimp-like preference experience, adapted to our category toggles.

• The visible unsubscribe link in an email opens the website preference page. The recipient can untick the categories they no longer want and submit the change; the page controls the website preference state.
• A supported Gmail/email-header unsubscribe action may apply the unsubscribe automatically without bringing the recipient to the website. It turns off the purpose/category represented by that email, is idempotent, and does not change unrelated categories.
• Non-optional verification and one-time requested Slack-access messages do not get an optional marketing unsubscribe control.

This supersedes the shorthand “confirmation first” wording: the body-link flow is a preference-center page, while the email-header action can be automatic. Mailchimp reference: About Unsubscribes. No code or provider configuration was changed.

[alexeygrigorev]

Owner decision 11 — Mailchimp subscription reconciliation — 2026-08-27

Mailchimp is authoritative for marketing/newsletter subscription state. Provide two explicit import operations:

• Import the Mailchimp subscribed list: matched legacy accounts become marketing-subscribed (toggle on).
• Import the Mailchimp unsubscribed list: matched accounts become marketing-unsubscribed (toggle off).

The two operations are separate and idempotent, affect only the marketing/newsletter preference, and do not infer event, Slack, course, or email-verification state. An unsubscribe import must turn off a currently subscribed platform account. No code or provider configuration was changed.