docs(openspec): add change artifacts for email-reply-to-addresses
Specifies Reply-To header behavior for the two outbound email types: - Confirmation emails to parents: Reply-To set to admin address (spielgruppen@familien-verein.ch) - Registration notification emails to leaders/admin: Reply-To set to parent's email https://claude.ai/code/session_014NynTjALA5TeP85mbr5ZA8
This commit is contained in:
Claude
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-02-27
|
||||
@@ -0,0 +1,47 @@
|
||||
## Context
|
||||
|
||||
The system sends emails in two directions with two different purposes:
|
||||
|
||||
- **Outbound to parents**: The AI agent sends conversational replies and, upon registration completion, a confirmation email summarising the registration and next steps.
|
||||
- **Outbound to admins/leaders**: The system sends a notification email to the relevant playgroup leader(s) and Markus Graf (CC) immediately after a registration is completed.
|
||||
|
||||
Email clients use the `Reply-To` header (falling back to `From`) to determine where a reply is directed. Without explicit `Reply-To` headers, all replies from both parents and admins flow back to the registration system's inbox — which is correct for ongoing conversation but wrong for post-completion follow-up.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Ensure parent replies to completion confirmation emails reach the admin (Markus Graf) rather than the agent pipeline
|
||||
- Ensure admin/leader replies to registration notification emails reach the registering parent directly
|
||||
- Formally specify `Reply-To` behavior in the relevant capability specs
|
||||
|
||||
**Non-Goals:**
|
||||
- Changing the `From` address of any email
|
||||
- Modifying conversational email behavior (mid-registration agent ↔ parent exchanges — these correctly use the registration address as both From and effective reply target)
|
||||
- Introducing any new email addresses beyond what is already configured
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Confirmation Email Reply-To: Admin Address
|
||||
|
||||
**Decision**: Set `Reply-To: spielgruppen@familien-verein.ch` (Markus Graf) on all confirmation emails sent to parents after registration completion.
|
||||
|
||||
**Rationale**: Once registration is complete, the conversation is over. Any parent reply is a human follow-up question — it should reach a human admin, not re-enter the agent pipeline. Markus Graf is the designated central admin contact and is already CC'd on all notifications.
|
||||
|
||||
**Alternatives considered**:
|
||||
- No Reply-To (default to From): Parent replies re-enter the agent inbox and may trigger unwanted agent responses post-completion.
|
||||
- Reply-To the relevant playgroup leader (Andrea/Barbara): More targeted, but leaders vary by registration type and parents may not know who they're reaching. The central admin address is simpler and consistent.
|
||||
|
||||
### 2. Notification Email Reply-To: Parent Address
|
||||
|
||||
**Decision**: Set `Reply-To: <parent email>` on all registration notification emails sent to admins/leaders.
|
||||
|
||||
**Rationale**: The primary reason admins reply to a notification is to contact the parent (e.g., to confirm a spot, ask a clarifying question, or provide further instructions). Pre-filling Reply-To with the parent's address eliminates a copy-paste step and reduces errors. This is already noted informally in `notification-template.md` — this change formalises it as a spec requirement.
|
||||
|
||||
**Alternatives considered**:
|
||||
- No Reply-To (default to From/registration inbox): Admins must manually copy the parent's email to reply, adding friction.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
**Admin confirmation email replies go to Markus, not directly to the leader**: For outdoor registrations, the leader is Barbara Gross, but parent replies to confirmation go to Markus Graf. This is acceptable — Markus can forward as needed, and having a single consistent Reply-To is simpler than routing by playgroup type.
|
||||
|
||||
**Mid-registration vs. post-registration distinction**: Conversational emails (mid-registration) should NOT set Reply-To to the admin — they must continue flowing back to the registration inbox so the agent can process them. The implementation must apply the admin Reply-To only to the final confirmation email, not to all outbound agent emails.
|
||||
@@ -0,0 +1,21 @@
|
||||
## Why
|
||||
|
||||
The system sends two distinct types of emails to different audiences with different needs for follow-up communication. Currently, the Reply-To behavior for these emails is either unspecified or inconsistent:
|
||||
|
||||
1. **Confirmation emails to parents** — sent by the agent after registration is complete. If a parent replies to this email, that reply should reach the admin (Markus Graf), not bounce back into the agent's inbox for further automated processing.
|
||||
|
||||
2. **Registration notification emails to playgroup leaders/admins** — sent to Andrea Sigrist, Barbara Gross, and Markus Graf when a new registration is submitted. If an admin wants to follow up with the parent directly, their reply must go to the parent's email, not back to the registration system.
|
||||
|
||||
Without explicit Reply-To configuration, email clients will default to replying to the From address (the registration system's email). This creates confusion: parent replies to confirmation emails enter the agent pipeline instead of reaching a human admin, and admin replies to notification emails go to the registration inbox rather than the parent.
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Confirmation emails**: Add a `Reply-To` header set to the admin email address (`spielgruppen@familien-verein.ch`) so parent replies reach a human directly
|
||||
- **Admin notification emails**: Confirm and formally specify that `Reply-To` is set to the parent's email address so admins can respond to parents directly from their email client
|
||||
|
||||
## Capabilities
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `email-channel`: Add Reply-To specification for confirmation emails sent to parents after registration completion
|
||||
- `registration-notifications`: Formally specify Reply-To for admin notification emails (parent's email address)
|
||||
@@ -0,0 +1,15 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Confirmation email sets Reply-To to admin address
|
||||
|
||||
The system SHALL set the `Reply-To` header to the admin email address (`spielgruppen@familien-verein.ch`) on the registration completion confirmation email sent to the parent.
|
||||
|
||||
#### Scenario: Parent replies to confirmation email
|
||||
- **WHEN** the agent sends a registration completion confirmation email to a parent
|
||||
- **THEN** the email SHALL include a `Reply-To` header set to `spielgruppen@familien-verein.ch`
|
||||
- **AND** a parent reply SHALL be delivered to the admin, not to the registration system's inbox
|
||||
|
||||
#### Scenario: Mid-registration emails are unaffected
|
||||
- **WHEN** the agent sends a conversational email during an ongoing registration (not the final confirmation)
|
||||
- **THEN** the email SHALL NOT set `Reply-To` to the admin address
|
||||
- **AND** parent replies SHALL continue to be routed back to the registration system for processing
|
||||
@@ -0,0 +1,18 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: Notification email sets Reply-To to parent address
|
||||
|
||||
The system SHALL set the `Reply-To` header to the registering parent's email address on all registration notification emails sent to playgroup leaders and the admin.
|
||||
|
||||
#### Scenario: Leader replies to notification email
|
||||
- **WHEN** a registration notification email is sent to a playgroup leader (Andrea Sigrist or Barbara Gross)
|
||||
- **THEN** the email SHALL include a `Reply-To` header set to the parent's email address (`registration.parentGuardian.email`)
|
||||
- **AND** a leader reply SHALL be delivered directly to the parent
|
||||
|
||||
#### Scenario: Admin (CC) replies to notification email
|
||||
- **WHEN** Markus Graf replies to a registration notification email (received as CC)
|
||||
- **THEN** the reply SHALL be delivered directly to the parent's email address
|
||||
|
||||
#### Scenario: Reply-To applies to all notification routing types
|
||||
- **WHEN** a notification is sent for an indoor-only, outdoor-only, or both registration
|
||||
- **THEN** all recipient copies (To and CC) SHALL have `Reply-To` set to the parent's email address
|
||||
@@ -0,0 +1,19 @@
|
||||
## 1. Confirmation Email Reply-To (Email Channel)
|
||||
|
||||
- [ ] 1.1 Identify where the registration completion confirmation email is constructed in `src/` (email channel adapter / agent core)
|
||||
- [ ] 1.2 Add `Reply-To: spielgruppen@familien-verein.ch` header to the confirmation email only (not to mid-registration conversational emails)
|
||||
- [ ] 1.3 Add a unit test verifying the `Reply-To` header is present on the confirmation email
|
||||
- [ ] 1.4 Add a unit test verifying mid-registration emails do NOT carry the admin `Reply-To` header
|
||||
|
||||
## 2. Notification Email Reply-To (Registration Notifications)
|
||||
|
||||
- [ ] 2.1 Identify where registration notification emails are constructed and sent
|
||||
- [ ] 2.2 Set `Reply-To: <parent email>` header on all outgoing notification emails (indoor, outdoor, and both routing types)
|
||||
- [ ] 2.3 Add a unit test verifying the `Reply-To` header equals the parent's email for indoor-only notification
|
||||
- [ ] 2.4 Add a unit test verifying the `Reply-To` header equals the parent's email for outdoor-only notification
|
||||
- [ ] 2.5 Add a unit test verifying the `Reply-To` header equals the parent's email when both leaders are notified
|
||||
|
||||
## 3. Verification
|
||||
|
||||
- [ ] 3.1 Run the full test suite and confirm all tests pass
|
||||
- [ ] 3.2 Manually send a test registration through the email channel and verify reply routing behaves correctly
|
||||
Reference in New Issue
Block a user