Email Notification Configuration System

Overview

The Email Notification Configuration System allows tenant administrators to selectively enable or disable transactional email notifications sent to end users. This feature enables tenants to integrate external email platforms (like Braze, Customer.io, or custom systems) without duplicating notifications.

Business Context

Publishers often want to:

• Implement custom email workflows through external marketing automation platforms
• Maintain brand consistency across all customer touchpoints
• Control notification timing and personalization beyond platform defaults
• Reduce notification fatigue by centralizing email delivery

This system provides granular ON/OFF controls for each transactional email type, allowing tenants to choose which notifications are handled by Publica.la and which are managed externally.

Scope

The system provides configuration for 5 transactional email types:

Email Type	Notification Class	Purpose
Welcome Email	WelcomeNotification	Sent when new users register
Publication Purchase Receipt	IssueInvoice	Sent after purchasing content
Subscription Receipt	PlanInvoice	Sent after subscribing to a plan
Gift Purchase Receipt	GiftInvoice	Sent after purchasing/receiving a gift
Shipping Status Updates	ShippingNoteNotification	Sent when shipping status changes

Important

System emails like password reset (CustomResetPassword) and login tokens (LoginTokenNotification) are NOT configurable and will always be sent regardless of these settings. These are critical for platform security and functionality.

Configuration Structure

Email notification settings are stored in TenantMeta->notifications['email_notifications'] as a JSON object:

{
  "welcome_email": true,
  "issue_invoice": true,
  "plan_invoice": true,
  "gift_invoice": true,
  "shipping_notification": true
}

Default Behavior

• All notifications enabled by default (true)
• Lazy initialization: Configuration is created only when first accessed/modified
• NULL-safe: Missing configuration defaults to enabled state (backward compatible)
• Tenant-isolated: Each tenant has independent configuration

User Interface

Administrators access email configuration through:

Dashboard → Settings → Notifications

The interface is organized into three categories:

1. Authentication

• Welcome Email: Sent after user registration

2. Purchases

• Publication Purchase Receipt: Sent after purchasing content
• Subscription Receipt: Sent after subscribing to a plan
• Gift Purchase Receipt: Sent after purchasing/receiving a gift

3. Shipping

• Shipping Status Updates: Sent when shipping status changes

Each notification has:

• Toggle switch: Enable/disable the notification
• Description: Explains when the email is sent
• Deferred sync: Changes are only saved when "Save" is clicked

Additional Admin Notifications

If the webhooks_api_integration feature is enabled, the Notifications settings page also includes:

Webhooks

• Notification URL: Endpoint to receive webhook notifications
• Webhook Key: Secure key for webhook authentication (can be regenerated)
• Test Button: Send a test webhook notification

Email Notifications (Admin)

• Notification Email: Admin email address for sale notifications
• Test Button: Send a test email notification

Business Rules

General Rules

1. Independent Configuration: Each email type can be enabled/disabled independently
2. Future-Only: Configuration applies only to future emails (not retroactive)
3. Tenant Isolation: Configuration is tenant-specific (doesn't affect other tenants)
4. Default Enabled: All emails default to true (maintains current behavior)
5. Activity Logging: All configuration changes are logged automatically via LogsActivity trait

Security & Audit

1. Access Control: Only tenant administrators can modify configuration
2. Validation: Configuration values are validated before saving
3. Error Logging: All exceptions are reported to Sentry
4. Audit Trail: Activity log records:
   • What changed (configuration diff)
   • Who changed it (user ID)
   • When it changed (timestamp)

System Emails (Non-Configurable)

The following emails are critical for platform operation and cannot be disabled:

• Password Reset (CustomResetPassword): Required for account recovery
• Login Token (LoginTokenNotification): Required for mobile app login
• Unpaid Invoices (UnpaidInvoices): Required for billing
• Export Reports (ExportReportGenerated): Required for data access
• Support Requests (UserSupportRequest, AppSupportRequest): Required for customer service

These emails will always be sent regardless of notification configuration.

Webhooks & Admin Notifications

Beyond user-facing transactional emails, the Notifications settings also manage:

Webhook Configuration

Allows tenants to receive webhook notifications for sales and events:

• Notification URL: HTTPS endpoint to receive webhooks
• Webhook Key: Authentication key (format: webhook-{uuid})
• Test Function: Send test webhook to verify integration

Storage: TenantMeta->integrations['webhooks']

Feature Flag: webhooks_api_integration

Admin Email Notifications

Allows tenants to receive email notifications about sales:

• Notification Email: Admin email address for alerts
• Test Function: Send test email to verify delivery

Storage: TenantMeta->integrations['email']['notification_email']

Feature Flag: webhooks_api_integration

Future Enhancements

Potential improvements to the notification system:

1. Schedule Controls: Allow timing rules (e.g., "don't send after 10pm")
2. User Preferences: Let end users control their notification preferences
3. A/B Testing: Toggle notifications for percentage of users
4. Preview: Show preview of email before enabling
5. Delivery Reports: Dashboard showing email delivery stats
6. Template Customization: Allow tenants to customize email templates
7. More Notification Types: Expand to cover all 20+ notification classes

Related Documentation

• Email Sending Schema - Complete catalog of all platform emails
• Activity Log Documentation - How configuration changes are tracked
• Webhook Documentation - External webhook integration guide
• Multi-tenant Architecture - How tenant isolation works