fix: resolve email settings architecture violations and add tests/docs
- Fix API-002 in admin/settings.py: use service layer for DB delete - Fix API-001/API-003 in vendor/email_settings.py: add Pydantic response models, remove HTTPException raises - Fix SVC-002/SVC-006 in vendor_email_settings_service.py: use domain exceptions, change db.commit() to db.flush() - Add unit tests for VendorEmailSettingsService - Add integration tests for vendor and admin email settings APIs - Add user guide (docs/guides/email-settings.md) - Add developer guide (docs/implementation/email-settings.md) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
254
docs/guides/email-settings.md
Normal file
254
docs/guides/email-settings.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# Email Settings Guide
|
||||
|
||||
This guide covers email configuration for both **vendors** and **platform administrators**. The Wizamart platform uses a layered email system where vendors manage their own email sending while the platform handles system-level communications.
|
||||
|
||||
## Overview
|
||||
|
||||
The email system has two distinct configurations:
|
||||
|
||||
| Aspect | Platform (Admin) | Vendor |
|
||||
|--------|-----------------|--------|
|
||||
| Purpose | System emails (billing, admin notifications) | Customer-facing emails (orders, marketing) |
|
||||
| Configuration | Environment variables (.env) + Database overrides | Database (per-vendor) |
|
||||
| Cost | Platform owner pays | Vendor pays |
|
||||
| Providers | SMTP, SendGrid, Mailgun, SES | SMTP (all tiers), Premium providers (Business+) |
|
||||
|
||||
---
|
||||
|
||||
## Vendor Email Settings
|
||||
|
||||
### Getting Started
|
||||
|
||||
As a vendor, you need to configure email settings to send emails to your customers. This includes order confirmations, shipping updates, and marketing emails.
|
||||
|
||||
#### Accessing Email Settings
|
||||
|
||||
1. Log in to your Vendor Dashboard
|
||||
2. Navigate to **Settings** from the sidebar
|
||||
3. Click on the **Email** tab
|
||||
|
||||
### Available Providers
|
||||
|
||||
| Provider | Tier Required | Best For |
|
||||
|----------|---------------|----------|
|
||||
| SMTP | All tiers | Standard email servers, most common |
|
||||
| SendGrid | Business+ | High-volume transactional emails |
|
||||
| Mailgun | Business+ | Developer-friendly API |
|
||||
| Amazon SES | Business+ | AWS ecosystem, cost-effective |
|
||||
|
||||
### Configuring SMTP
|
||||
|
||||
SMTP is available for all subscription tiers. Common SMTP providers include:
|
||||
- Gmail (smtp.gmail.com:587)
|
||||
- Microsoft 365 (smtp.office365.com:587)
|
||||
- Your hosting provider's SMTP server
|
||||
|
||||
**Required Fields:**
|
||||
- **From Email**: The sender email address (e.g., orders@yourstore.com)
|
||||
- **From Name**: The sender display name (e.g., "Your Store")
|
||||
- **SMTP Host**: Your SMTP server address
|
||||
- **SMTP Port**: Usually 587 (TLS) or 465 (SSL)
|
||||
- **SMTP Username**: Your login username
|
||||
- **SMTP Password**: Your login password
|
||||
- **Use TLS**: Enable for port 587 (recommended)
|
||||
- **Use SSL**: Enable for port 465
|
||||
|
||||
### Configuring Premium Providers (Business+)
|
||||
|
||||
If you have a Business or Enterprise subscription, you can use premium email providers:
|
||||
|
||||
#### SendGrid
|
||||
1. Create a SendGrid account at [sendgrid.com](https://sendgrid.com)
|
||||
2. Generate an API key
|
||||
3. Enter the API key in your vendor settings
|
||||
|
||||
#### Mailgun
|
||||
1. Create a Mailgun account at [mailgun.com](https://mailgun.com)
|
||||
2. Add and verify your domain
|
||||
3. Get your API key from the dashboard
|
||||
4. Enter the API key and domain in your settings
|
||||
|
||||
#### Amazon SES
|
||||
1. Set up SES in your AWS account
|
||||
2. Verify your sender domain/email
|
||||
3. Create IAM credentials with SES permissions
|
||||
4. Enter the access key, secret key, and region
|
||||
|
||||
### Verifying Your Configuration
|
||||
|
||||
After configuring your email settings:
|
||||
|
||||
1. Click **Save Settings**
|
||||
2. Enter a test email address in the **Test Email** field
|
||||
3. Click **Send Test**
|
||||
4. Check your inbox for the test email
|
||||
|
||||
If the test fails, check:
|
||||
- Your credentials are correct
|
||||
- Your IP/domain is not blocked
|
||||
- For Gmail: Allow "less secure apps" or use an app password
|
||||
|
||||
### Email Warning Banner
|
||||
|
||||
Until you configure and verify your email settings, you'll see a warning banner at the top of your dashboard. This ensures you don't forget to set up email before your store goes live.
|
||||
|
||||
---
|
||||
|
||||
## Platform Admin Email Settings
|
||||
|
||||
### Overview
|
||||
|
||||
Platform administrators can configure system-wide email settings for platform communications like:
|
||||
- Subscription billing notifications
|
||||
- Admin alerts
|
||||
- Platform-wide announcements
|
||||
|
||||
### Configuration Sources
|
||||
|
||||
Admin email settings support two configuration sources:
|
||||
|
||||
1. **Environment Variables (.env)** - Default configuration
|
||||
2. **Database Overrides** - Override .env via the admin UI
|
||||
|
||||
Database settings take priority over .env values.
|
||||
|
||||
### Accessing Admin Email Settings
|
||||
|
||||
1. Log in to the Admin Panel
|
||||
2. Navigate to **Settings**
|
||||
3. Click on the **Email** tab
|
||||
|
||||
### Viewing Current Configuration
|
||||
|
||||
The Email tab shows:
|
||||
- **Provider**: Current email provider (SMTP, SendGrid, etc.)
|
||||
- **From Email**: Sender email address
|
||||
- **From Name**: Sender display name
|
||||
- **Status**: Whether email is configured and enabled
|
||||
- **DB Overrides**: Whether database overrides are active
|
||||
|
||||
### Editing Settings
|
||||
|
||||
Click **Edit Settings** to modify the email configuration:
|
||||
|
||||
1. Select the email provider
|
||||
2. Enter the required credentials
|
||||
3. Configure enabled/debug flags
|
||||
4. Click **Save Email Settings**
|
||||
|
||||
### Resetting to .env Defaults
|
||||
|
||||
If you've made database overrides and want to revert to .env configuration:
|
||||
|
||||
1. Click **Reset to .env Defaults**
|
||||
2. Confirm the action
|
||||
|
||||
This removes all email settings from the database, reverting to .env values.
|
||||
|
||||
### Testing Configuration
|
||||
|
||||
1. Enter a test email address
|
||||
2. Click **Send Test**
|
||||
3. Check your inbox
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables Reference
|
||||
|
||||
For platform configuration via .env:
|
||||
|
||||
```env
|
||||
# Provider: smtp, sendgrid, mailgun, ses
|
||||
EMAIL_PROVIDER=smtp
|
||||
|
||||
# Sender identity
|
||||
EMAIL_FROM_ADDRESS=noreply@yourplatform.com
|
||||
EMAIL_FROM_NAME=Your Platform
|
||||
EMAIL_REPLY_TO=support@yourplatform.com
|
||||
|
||||
# Behavior
|
||||
EMAIL_ENABLED=true
|
||||
EMAIL_DEBUG=false
|
||||
|
||||
# SMTP Configuration
|
||||
SMTP_HOST=smtp.example.com
|
||||
SMTP_PORT=587
|
||||
SMTP_USER=your-username
|
||||
SMTP_PASSWORD=your-password
|
||||
SMTP_USE_TLS=true
|
||||
SMTP_USE_SSL=false
|
||||
|
||||
# SendGrid
|
||||
SENDGRID_API_KEY=your-api-key
|
||||
|
||||
# Mailgun
|
||||
MAILGUN_API_KEY=your-api-key
|
||||
MAILGUN_DOMAIN=mg.yourdomain.com
|
||||
|
||||
# Amazon SES
|
||||
AWS_ACCESS_KEY_ID=your-access-key
|
||||
AWS_SECRET_ACCESS_KEY=your-secret-key
|
||||
AWS_REGION=eu-west-1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tier-Based Branding
|
||||
|
||||
The email system includes tier-based branding for vendor emails:
|
||||
|
||||
| Tier | Branding |
|
||||
|------|----------|
|
||||
| Essential | "Powered by Wizamart" footer |
|
||||
| Professional | "Powered by Wizamart" footer |
|
||||
| Business | No branding (white-label) |
|
||||
| Enterprise | No branding (white-label) |
|
||||
|
||||
Business and Enterprise tier vendors get completely white-labeled emails with no Wizamart branding.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Email sending is disabled"**
|
||||
- Check that `EMAIL_ENABLED=true` in .env
|
||||
- Or enable it in the admin settings
|
||||
|
||||
**"Connection refused" on SMTP**
|
||||
- Verify SMTP host and port
|
||||
- Check firewall rules
|
||||
- Ensure TLS/SSL settings match your server
|
||||
|
||||
**"Authentication failed"**
|
||||
- Double-check username/password
|
||||
- For Gmail, use an App Password
|
||||
- For Microsoft 365, check MFA requirements
|
||||
|
||||
**"SendGrid error: 403"**
|
||||
- Verify your API key has Mail Send permissions
|
||||
- Check sender identity is verified
|
||||
|
||||
**Premium provider not available**
|
||||
- Upgrade to Business or Enterprise tier
|
||||
- Contact support if you have the right tier but can't access
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug mode to log emails instead of sending them:
|
||||
- Set `EMAIL_DEBUG=true` in .env
|
||||
- Or enable "Debug mode" in admin settings
|
||||
|
||||
Debug mode logs the email content to the server logs without actually sending.
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Never share API keys or passwords** in logs or frontend
|
||||
2. **Use environment variables** for sensitive credentials
|
||||
3. **Enable TLS** for SMTP connections
|
||||
4. **Verify sender domains** with your email provider
|
||||
5. **Monitor email logs** for delivery issues
|
||||
6. **Rotate credentials** periodically
|
||||
Reference in New Issue
Block a user