first commit

about/email_spec.md

@@ -0,0 +1,299 @@
+# Spanglish Website – Email System Specification
+
+## 1. Purpose
+
+This document defines all email communications sent by the Spanglish platform.
+
+The goal is to provide clear, reliable communication without unnecessary automation or spam.
+
+All emails must support event management, trust, and community growth.
+
+---
+
+## 2. Core Principles
+
+* Bookings are only confirmed after payment
+* No automatic reminders based on cron jobs
+* No automatic cash reminders
+* Follow-up emails are sent manually
+* Event-specific communication must be possible
+* Emails must be intentional and relevant
+
+---
+
+## 3. Booking Confirmation Policy
+
+### 3.1 Payment Requirement
+
+A booking is considered "Confirmed" only when:
+
+* Card payment is verified, or
+* Lightning payment is verified, or
+* Cash payment is marked as received by staff
+
+Unpaid cash reservations are not considered confirmed.
+
+---
+
+### 3.2 Confirmation Email
+
+Sent only after payment is confirmed.
+
+Trigger:
+
+* Payment webhook (Card / Lightning)
+* Manual admin confirmation (Cash)
+
+Purpose:
+
+* Official confirmation
+* Proof of participation
+
+---
+
+## 4. Supported Email Types
+
+### 4.1 Booking Confirmation (Automatic)
+
+Sent when payment is confirmed.
+
+Trigger:
+
+* Payment verification
+* Manual confirmation
+
+Subject Example:
+Your Spanglish ticket is confirmed 🎉
+
+Content includes:
+
+* Event name
+* Date and time
+* Location and map
+* Payment method
+* Ticket ID
+* Contact info
+
+---
+
+### 4.2 Payment Receipt (Automatic)
+
+Sent for Card and Lightning payments.
+
+Trigger:
+
+* Payment provider webhook
+
+Purpose:
+
+* Financial confirmation
+* Transparency
+
+Content includes:
+
+* Amount
+* Method
+* Reference ID
+
+---
+
+### 4.3 Event Update / Custom Message (Manual)
+
+Sent manually by admin per event.
+
+Trigger:
+
+* Admin action
+
+Purpose:
+
+* Inform attendees about changes
+* Share important information
+* Handle exceptional situations
+
+Examples:
+
+* Location change
+* Time change
+* Special instructions
+* Delays
+* Guest speakers
+
+Admin must be able to:
+
+* Write custom subject
+* Write custom body
+* Select target event
+* Preview before sending
+
+---
+
+### 4.4 Post-Event Follow-Up (Manual)
+
+Sent manually after the event.
+
+Trigger:
+
+* Admin action
+
+Purpose:
+
+* Thank attendees
+* Share photos
+* Promote next event
+* Build loyalty
+
+This email is never automated.
+
+---
+
+## 5. Disabled / Unsupported Emails
+
+The system must NOT send:
+
+* Automatic cash payment reminders
+* Automated event reminders
+* Cron-based scheduled emails
+* Repeated promotional spam
+
+All non-critical communication is manual.
+
+---
+
+## 6. Admin Email Interface
+
+### 6.1 Email Center
+
+The admin dashboard must include an Email Center with:
+
+* List of past emails
+* Draft editor
+* Template library
+* Recipient selector
+* Preview mode
+* Send confirmation
+
+---
+
+### 6.2 Recipient Selection
+
+Admins must be able to target:
+
+* All attendees of an event
+* Only confirmed attendees
+* Only unpaid attendees
+* Custom subsets
+
+Selection must be explicit before sending.
+
+---
+
+## 7. Templates
+
+### 7.1 Default Templates
+
+System-provided templates:
+
+* Booking confirmation
+* Payment receipt
+* Event update
+* Follow-up
+
+Templates are editable.
+
+---
+
+### 7.2 Custom Templates
+
+Admins may create custom templates per event.
+
+Templates support:
+
+* Variables (name, event, date)
+* Preview rendering
+* Versioning
+
+---
+
+## 8. Sending Logic
+
+### 8.1 Manual Sending
+
+Most emails are sent manually from the admin panel.
+
+The system must require:
+
+* Explicit confirmation
+* Recipient preview
+* Final approval
+
+---
+
+### 8.2 Automatic Sending
+
+Only the following emails may be automatic:
+
+* Booking confirmation (after payment)
+* Payment receipt
+
+No other automatic emails are allowed.
+
+---
+
+## 9. Logging & Auditing
+
+All email activity must be logged:
+
+* Sender (admin)
+* Recipients
+* Subject
+* Timestamp
+* Event reference
+* Delivery status
+
+Logs are visible to admins.
+
+---
+
+## 10. Deliverability Requirements
+
+* Use verified sender domain
+* DKIM and SPF enabled
+* Bounce handling
+* Unsubscribe support
+
+---
+
+## 11. Design Rules
+
+All emails must follow brand guidelines:
+
+* White background
+* Logo header
+* Clean typography
+* Mobile-friendly layout
+* One main CTA
+* No clutter
+
+---
+
+## 12. Future Extensions
+
+Possible future additions:
+
+* WhatsApp integration
+* SMS notifications
+* Smart segmentation
+* Automated campaigns (opt-in only)
+
+All future automation requires explicit approval.
+
+---
+
+## 13. Summary
+
+The Spanglish email system prioritizes clarity, trust, and human control.
+
+Only critical confirmations are automated.
+
+All community and relationship communication remains manual and intentional.