Custom message
", + body_text="Hello\n\nCustom message", +) +``` + +## Email Templates + +### Creating Templates + +Templates use Jinja2 syntax for variable interpolation: + +```html +Hello {{ first_name }},
+Welcome to {{ company_name }}!
+``` + +### Seeding Templates + +Run the seed script to populate default templates: + +```bash +python scripts/seed_email_templates.py +``` + +This creates templates for: + +- `signup_welcome` (en, fr, de, lb) + +### Available Variables + +For `signup_welcome`: + +| Variable | Description | +|----------|-------------| +| first_name | User's first name | +| company_name | Vendor company name | +| email | User's email address | +| vendor_code | Vendor code for dashboard URL | +| login_url | Direct link to dashboard | +| trial_days | Number of trial days | +| tier_name | Subscription tier name | + +## Provider Setup + +### SMTP + +Standard SMTP configuration: + +```env +EMAIL_PROVIDER=smtp +SMTP_HOST=smtp.gmail.com +SMTP_PORT=587 +SMTP_USER=your-email@gmail.com +SMTP_PASSWORD=your-app-password +SMTP_USE_TLS=true +``` + +### SendGrid + +1. Create account at [sendgrid.com](https://sendgrid.com) +2. Generate API key in Settings > API Keys +3. Configure: + +```env +EMAIL_PROVIDER=sendgrid +SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxx +``` + +4. Install package: `pip install sendgrid` + +### Mailgun + +1. Create account at [mailgun.com](https://mailgun.com) +2. Add and verify your domain +3. Get API key from Domain Settings +4. Configure: + +```env +EMAIL_PROVIDER=mailgun +MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxx +MAILGUN_DOMAIN=mg.yourdomain.com +``` + +### Amazon SES + +1. Set up SES in AWS Console +2. Verify sender domain/email +3. Create IAM user with SES permissions +4. Configure: + +```env +EMAIL_PROVIDER=ses +AWS_ACCESS_KEY_ID=AKIAXXXXXXXXXXXXXXXX +AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +AWS_REGION=eu-west-1 +``` + +5. Install package: `pip install boto3` + +## Email Logging + +All emails are logged to the `email_logs` table. Query examples: + +```python +# Get failed emails +failed = db.query(EmailLog).filter( + EmailLog.status == EmailStatus.FAILED.value +).all() + +# Get emails for a vendor +vendor_emails = db.query(EmailLog).filter( + EmailLog.vendor_id == vendor_id +).order_by(EmailLog.created_at.desc()).all() + +# Get recent signup emails +signups = db.query(EmailLog).filter( + EmailLog.template_code == "signup_welcome", + EmailLog.created_at >= datetime.now() - timedelta(days=7) +).all() +``` + +## Language Fallback + +The system automatically falls back to English if a template isn't available in the requested language: + +1. Request template for "de" (German) +2. If not found, try "en" (English) +3. If still not found, return None (log error) + +## Testing + +Run email service tests: + +```bash +pytest tests/unit/services/test_email_service.py -v +``` + +Test coverage includes: + +- Provider abstraction (Debug, SMTP, etc.) +- Template rendering with Jinja2 +- Language fallback behavior +- Email sending success/failure +- EmailLog model methods +- Template variable handling + +## Architecture + +``` +app/services/email_service.py # Email service with provider abstraction +models/database/email.py # EmailTemplate and EmailLog models +app/core/config.py # Email configuration settings +scripts/seed_email_templates.py # Template seeding script +``` + +### Provider Abstraction + +The system uses a strategy pattern for email providers: + +``` +EmailProvider (ABC) +├── SMTPProvider +├── SendGridProvider +├── MailgunProvider +├── SESProvider +└── DebugProvider +``` + +Each provider implements the `send()` method with the same signature, making it easy to switch providers via configuration. + +## Future Enhancements + +Planned improvements: + +1. **Email Queue**: Background task queue for high-volume sending +2. **Webhook Tracking**: Track deliveries, opens, clicks via provider webhooks +3. **Template Editor**: Admin UI for editing templates +4. **A/B Testing**: Test different email versions +5. **Scheduled Emails**: Send emails at specific times diff --git a/mkdocs.yml b/mkdocs.yml index 793494df..c6101f48 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -201,6 +201,7 @@ nav: - Platform Homepage: features/platform-homepage.md - Vendor Landing Pages: features/vendor-landing-pages.md - Subscription & Billing: features/subscription-billing.md + - Email System: features/email-system.md # --- User Guides --- - User Guides: diff --git a/models/database/__init__.py b/models/database/__init__.py index 52138194..d959a781 100644 --- a/models/database/__init__.py +++ b/models/database/__init__.py @@ -18,6 +18,7 @@ from .base import Base from .company import Company from .content_page import ContentPage from .customer import Customer, CustomerAddress +from .email import EmailCategory, EmailLog, EmailStatus, EmailTemplate from .inventory import Inventory from .invoice import ( Invoice, @@ -101,6 +102,11 @@ __all__ = [ # Customer "Customer", "CustomerAddress", + # Email + "EmailCategory", + "EmailLog", + "EmailStatus", + "EmailTemplate", # Product - Enums "ProductType", "DigitalDeliveryMethod", diff --git a/models/database/email.py b/models/database/email.py new file mode 100644 index 00000000..cfccfa8a --- /dev/null +++ b/models/database/email.py @@ -0,0 +1,192 @@ +# models/database/email.py +""" +Email system database models. + +Provides: +- EmailTemplate: Multi-language email templates stored in database +- EmailLog: Email sending history and tracking +""" + +import enum +from datetime import datetime + +from sqlalchemy import ( + Boolean, + Column, + DateTime, + Enum, + ForeignKey, + Integer, + String, + Text, +) +from sqlalchemy.orm import relationship + +from app.core.database import Base + +from .base import TimestampMixin + + +class EmailCategory(str, enum.Enum): + """Email template categories.""" + + AUTH = "auth" # signup, password reset, verification + ORDERS = "orders" # order confirmations, shipping + BILLING = "billing" # invoices, payment failures + SYSTEM = "system" # team invites, notifications + MARKETING = "marketing" # newsletters, promotions + + +class EmailStatus(str, enum.Enum): + """Email sending status.""" + + PENDING = "pending" + SENT = "sent" + FAILED = "failed" + BOUNCED = "bounced" + DELIVERED = "delivered" + OPENED = "opened" + CLICKED = "clicked" + + +class EmailTemplate(Base, TimestampMixin): + """ + Multi-language email templates. + + Templates use Jinja2 syntax for variable interpolation. + Each template can have multiple language versions. + """ + + __tablename__ = "email_templates" + + id = Column(Integer, primary_key=True, index=True) + + # Template identification + code = Column(String(100), nullable=False, index=True) # e.g., "signup_welcome" + language = Column(String(5), nullable=False, default="en") # e.g., "en", "fr", "de", "lb" + + # Template metadata + name = Column(String(255), nullable=False) # Human-readable name + description = Column(Text, nullable=True) # Template purpose description + category = Column( + String(50), default=EmailCategory.SYSTEM.value, nullable=False, index=True + ) + + # Email content + subject = Column(String(500), nullable=False) # Subject line (supports variables) + body_html = Column(Text, nullable=False) # HTML body + body_text = Column(Text, nullable=True) # Plain text fallback + + # Template variables (JSON list of expected variables) + # e.g., ["first_name", "company_name", "login_url"] + variables = Column(Text, nullable=True) + + # Status + is_active = Column(Boolean, default=True, nullable=False) + + # Unique constraint: one template per code+language + __table_args__ = ( + {"sqlite_autoincrement": True}, + ) + + def __repr__(self): + return f"Hi {{ first_name }},
+ +Thank you for signing up for Wizamart! Your account for {{ company_name }} is now active.
+ +Vendor Code: {{ vendor_code }}
+Plan: {{ tier_name }}
+Trial Period: {{ trial_days }} days free
+You can start managing your orders, inventory, and invoices right away:
+ + + ++ If you have any questions, just reply to this email or visit our help center. +
+ +Best regards,
The Wizamart Team
© 2024 Wizamart. Built for Luxembourg e-commerce.
+Bonjour {{ first_name }},
+ +Merci de vous être inscrit sur Wizamart ! Votre compte pour {{ company_name }} est maintenant actif.
+ +Code vendeur : {{ vendor_code }}
+Forfait : {{ tier_name }}
+Période d'essai : {{ trial_days }} jours gratuits
+Vous pouvez commencer à gérer vos commandes, stocks et factures dès maintenant :
+ + + ++ Si vous avez des questions, répondez simplement à cet email. +
+ +Cordialement,
L'équipe Wizamart
© 2024 Wizamart. Conçu pour le e-commerce luxembourgeois.
+Hallo {{ first_name }},
+ +Vielen Dank für Ihre Anmeldung bei Wizamart! Ihr Konto für {{ company_name }} ist jetzt aktiv.
+ +Verkäufercode: {{ vendor_code }}
+Tarif: {{ tier_name }}
+Testzeitraum: {{ trial_days }} Tage kostenlos
+Sie können sofort mit der Verwaltung Ihrer Bestellungen, Bestände und Rechnungen beginnen:
+ + + ++ Bei Fragen antworten Sie einfach auf diese E-Mail. +
+ +Mit freundlichen Grüßen,
Das Wizamart-Team
© 2024 Wizamart. Entwickelt für den luxemburgischen E-Commerce.
+Moien {{ first_name }},
+ +Merci fir d'Umeldung op Wizamart! Äre Kont fir {{ company_name }} ass elo aktiv.
+ +Verkeefer Code: {{ vendor_code }}
+Plang: {{ tier_name }}
+Testperiod: {{ trial_days }} Deeg gratis
+Dir kënnt direkt ufänken Är Bestellungen, Lager a Rechnungen ze verwalten:
+ + + ++ Wann Dir Froen hutt, äntwert einfach op dës E-Mail. +
+ +Mat beschte Gréiss,
D'Wizamart Team
© 2024 Wizamart. Gemaach fir de lëtzebuergeschen E-Commerce.
+Test
", + category=EmailCategory.SYSTEM.value, + ) + db.add(template) + db.commit() + + service = EmailService(db) + + # Request German, should fallback to English + result = service.get_template("test_template", "de") + + assert result is not None + assert result.language == "en" + + # Cleanup + db.delete(template) + db.commit() + + def test_get_template_specific_language(self, db): + """Test get_template returns specific language if available.""" + # Create templates in both languages + template_en = EmailTemplate( + code="test_lang_template", + language="en", + name="Test Template EN", + subject="English Subject", + body_html="English
", + category=EmailCategory.SYSTEM.value, + ) + template_fr = EmailTemplate( + code="test_lang_template", + language="fr", + name="Test Template FR", + subject="French Subject", + body_html="Français
", + category=EmailCategory.SYSTEM.value, + ) + db.add(template_en) + db.add(template_fr) + db.commit() + + service = EmailService(db) + + # Request French + result = service.get_template("test_lang_template", "fr") + + assert result is not None + assert result.language == "fr" + assert result.subject == "French Subject" + + # Cleanup + db.delete(template_en) + db.delete(template_fr) + db.commit() + + +@pytest.mark.unit +@pytest.mark.email +class TestEmailSending: + """Test suite for email sending functionality.""" + + @patch("app.services.email_service.get_provider") + @patch("app.services.email_service.settings") + def test_send_raw_success(self, mock_settings, mock_get_provider, db): + """Test successful raw email sending.""" + # Setup mocks + mock_settings.email_enabled = True + mock_settings.email_from_address = "noreply@test.com" + mock_settings.email_from_name = "Test" + mock_settings.email_reply_to = "" + mock_settings.email_provider = "smtp" + + mock_provider = MagicMock() + mock_provider.send.return_value = (True, "msg-123", None) + mock_get_provider.return_value = mock_provider + + service = EmailService(db) + + log = service.send_raw( + to_email="user@example.com", + to_name="User", + subject="Test Subject", + body_html="Welcome {{ first_name }} to {{ company }}
", + body_text="Welcome {{ first_name }} to {{ company }}", + category=EmailCategory.SYSTEM.value, + ) + db.add(template) + db.commit() + + # Setup mocks + mock_settings.email_enabled = True + mock_settings.email_from_address = "noreply@test.com" + mock_settings.email_from_name = "Test" + mock_settings.email_reply_to = "" + mock_settings.email_provider = "smtp" + + mock_provider = MagicMock() + mock_provider.send.return_value = (True, "msg-456", None) + mock_get_provider.return_value = mock_provider + + service = EmailService(db) + + log = service.send_template( + template_code="test_send_template", + to_email="user@example.com", + language="en", + variables={ + "first_name": "John", + "company": "ACME Corp" + }, + ) + + assert log.status == EmailStatus.SENT.value + assert log.template_code == "test_send_template" + assert log.subject == "Hello John" + + # Cleanup + db.delete(template) + db.commit() + + def test_send_template_not_found(self, db): + """Test sending with non-existent template.""" + service = EmailService(db) + + log = service.send_template( + template_code="nonexistent_template", + to_email="user@example.com", + ) + + assert log.status == EmailStatus.FAILED.value + assert "not found" in log.error_message.lower() + + +@pytest.mark.unit +@pytest.mark.email +class TestEmailLog: + """Test suite for EmailLog model methods.""" + + def test_mark_sent(self, db): + """Test EmailLog.mark_sent method.""" + log = EmailLog( + recipient_email="test@example.com", + subject="Test", + from_email="noreply@test.com", + status=EmailStatus.PENDING.value, + ) + db.add(log) + db.flush() + + log.mark_sent("provider-msg-id") + + assert log.status == EmailStatus.SENT.value + assert log.sent_at is not None + assert log.provider_message_id == "provider-msg-id" + + db.rollback() + + def test_mark_failed(self, db): + """Test EmailLog.mark_failed method.""" + log = EmailLog( + recipient_email="test@example.com", + subject="Test", + from_email="noreply@test.com", + status=EmailStatus.PENDING.value, + retry_count=0, + ) + db.add(log) + db.flush() + + log.mark_failed("Connection timeout") + + assert log.status == EmailStatus.FAILED.value + assert log.error_message == "Connection timeout" + assert log.retry_count == 1 + + db.rollback() + + def test_mark_delivered(self, db): + """Test EmailLog.mark_delivered method.""" + log = EmailLog( + recipient_email="test@example.com", + subject="Test", + from_email="noreply@test.com", + status=EmailStatus.SENT.value, + ) + db.add(log) + db.flush() + + log.mark_delivered() + + assert log.status == EmailStatus.DELIVERED.value + assert log.delivered_at is not None + + db.rollback() + + def test_mark_opened(self, db): + """Test EmailLog.mark_opened method.""" + log = EmailLog( + recipient_email="test@example.com", + subject="Test", + from_email="noreply@test.com", + status=EmailStatus.DELIVERED.value, + ) + db.add(log) + db.flush() + + log.mark_opened() + + assert log.status == EmailStatus.OPENED.value + assert log.opened_at is not None + + db.rollback() + + +@pytest.mark.unit +@pytest.mark.email +class TestEmailTemplate: + """Test suite for EmailTemplate model.""" + + def test_variables_list_property(self, db): + """Test EmailTemplate.variables_list property.""" + template = EmailTemplate( + code="test_vars", + language="en", + name="Test", + subject="Test", + body_html="Test
", + category=EmailCategory.SYSTEM.value, + variables=json.dumps(["first_name", "last_name", "email"]), + ) + db.add(template) + db.flush() + + assert template.variables_list == ["first_name", "last_name", "email"] + + db.rollback() + + def test_variables_list_empty(self, db): + """Test EmailTemplate.variables_list with no variables.""" + template = EmailTemplate( + code="test_no_vars", + language="en", + name="Test", + subject="Test", + body_html="Test
", + category=EmailCategory.SYSTEM.value, + variables=None, + ) + db.add(template) + db.flush() + + assert template.variables_list == [] + + db.rollback() + + def test_variables_list_invalid_json(self, db): + """Test EmailTemplate.variables_list with invalid JSON.""" + template = EmailTemplate( + code="test_invalid_json", + language="en", + name="Test", + subject="Test", + body_html="Test
", + category=EmailCategory.SYSTEM.value, + variables="not valid json", + ) + db.add(template) + db.flush() + + assert template.variables_list == [] + + db.rollback() + + def test_template_repr(self, db): + """Test EmailTemplate string representation.""" + template = EmailTemplate( + code="signup_welcome", + language="en", + name="Welcome", + subject="Welcome", + body_html="Welcome
", + category=EmailCategory.AUTH.value, + ) + + assert "signup_welcome" in repr(template) + assert "en" in repr(template) + + +@pytest.mark.unit +@pytest.mark.email +class TestSignupWelcomeEmail: + """Test suite for signup welcome email integration.""" + + @pytest.fixture + def welcome_template(self, db): + """Create a welcome template for testing.""" + import json + + template = EmailTemplate( + code="signup_welcome", + language="en", + name="Signup Welcome", + subject="Welcome {{ first_name }}!", + body_html="Welcome {{ first_name }} to {{ company_name }}
", + body_text="Welcome {{ first_name }} to {{ company_name }}", + category=EmailCategory.AUTH.value, + variables=json.dumps([ + "first_name", "company_name", "email", "vendor_code", + "login_url", "trial_days", "tier_name" + ]), + ) + db.add(template) + db.commit() + + yield template + + # Cleanup + db.delete(template) + db.commit() + + def test_welcome_template_rendering(self, db, welcome_template): + """Test that welcome template renders correctly.""" + service = EmailService(db) + + template = service.get_template("signup_welcome", "en") + assert template is not None + assert template.code == "signup_welcome" + + # Test rendering + rendered = service.render_template( + template.subject, + {"first_name": "John"} + ) + assert rendered == "Welcome John!" + + def test_welcome_template_has_required_variables(self, db, welcome_template): + """Test welcome template has all required variables.""" + template = ( + db.query(EmailTemplate) + .filter( + EmailTemplate.code == "signup_welcome", + EmailTemplate.language == "en", + ) + .first() + ) + + assert template is not None + + required_vars = [ + "first_name", + "company_name", + "vendor_code", + "login_url", + "trial_days", + "tier_name", + ] + + for var in required_vars: + assert var in template.variables_list, f"Missing variable: {var}" + + @patch("app.services.email_service.get_provider") + @patch("app.services.email_service.settings") + def test_welcome_email_send(self, mock_settings, mock_get_provider, db, welcome_template): + """Test sending welcome email.""" + # Setup mocks + mock_settings.email_enabled = True + mock_settings.email_from_address = "noreply@test.com" + mock_settings.email_from_name = "Test" + mock_settings.email_reply_to = "" + mock_settings.email_provider = "smtp" + + mock_provider = MagicMock() + mock_provider.send.return_value = (True, "welcome-msg-123", None) + mock_get_provider.return_value = mock_provider + + service = EmailService(db) + + log = service.send_template( + template_code="signup_welcome", + to_email="newuser@example.com", + to_name="John Doe", + language="en", + variables={ + "first_name": "John", + "company_name": "ACME Corp", + "email": "newuser@example.com", + "vendor_code": "ACME", + "login_url": "https://wizamart.com/vendor/ACME/dashboard", + "trial_days": 30, + "tier_name": "Essential", + }, + vendor_id=1, + user_id=1, + related_type="signup", + ) + + assert log.status == EmailStatus.SENT.value + assert log.template_code == "signup_welcome" + assert log.subject == "Welcome John!" + assert log.recipient_email == "newuser@example.com"