mirror of
https://github.com/usmannasir/cyberpanel.git
synced 2026-03-11 14:50:13 +01:00
Add CyberMail Email Delivery integration
- New emailDelivery Django app with full platform API integration - Account connection, domain management, SMTP credentials, relay config - Auto-configure SPF/DKIM/DMARC DNS records via PowerDNS - Postfix SMTP relay through CyberMail (configureRelayHost/removeRelayHost) - Real-time delivery logs, stats, and per-domain analytics - Single-page AngularJS dashboard with marketing landing page - Promotional banners on 6 email-related pages with dismiss cookie - Manual SQL table creation in upgrade.py for existing installs - Documentation: setup guide, technical reference, user guide
This commit is contained in:
usmannasir
266
docs/CYBERMAIL_SETUP_GUIDE.md
Normal file
266
docs/CYBERMAIL_SETUP_GUIDE.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# CyberMail Email Delivery — Setup & Administration Guide
|
||||
|
||||
**Feature**: CyberMail Email Delivery Integration
|
||||
**CyberPanel Version**: 2.4.5+
|
||||
**Platform**: https://platform.cyberpersons.com
|
||||
**Last Updated**: 2026-03-06
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
CyberMail Email Delivery is a built-in CyberPanel feature that routes outgoing emails through CyberMail's optimized delivery infrastructure. It solves common email deliverability problems — emails landing in spam, IP blacklisting, missing DNS records — by providing dedicated sending servers, automatic DNS configuration, and real-time delivery analytics.
|
||||
|
||||
### Key Benefits
|
||||
|
||||
- **15,000 emails/month free** on the Free plan
|
||||
- **Automatic DNS setup** — SPF, DKIM, and DMARC records configured in one click
|
||||
- **SMTP relay** — route all server email through CyberMail with one toggle
|
||||
- **Real-time analytics** — delivery logs, bounce tracking, reputation monitoring
|
||||
- **Multi-region delivery** — 4 delivery nodes with 99.9% uptime SLA
|
||||
- **98%+ inbox rate** across major providers (Gmail, Outlook, Yahoo)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. CyberPanel 2.4.5 or later installed
|
||||
2. Active internet connection from the server
|
||||
3. PowerDNS running (for automatic DNS configuration)
|
||||
4. Postfix installed (for SMTP relay feature)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
The CyberMail module is included in CyberPanel 2.4.5+. No separate installation needed.
|
||||
|
||||
### Verify the Module
|
||||
|
||||
```bash
|
||||
# Check the app exists
|
||||
ls /usr/local/CyberCP/emailDelivery/
|
||||
|
||||
# Check it's in INSTALLED_APPS
|
||||
grep -n "emailDelivery" /usr/local/CyberCP/CyberCP/settings.py
|
||||
|
||||
# Run migrations if needed
|
||||
cd /usr/local/CyberCP
|
||||
python manage.py migrate emailDelivery
|
||||
```
|
||||
|
||||
### Database Tables
|
||||
|
||||
The module creates two tables:
|
||||
|
||||
| Table | Purpose |
|
||||
|-------|---------|
|
||||
| `cybermail_accounts` | Stores per-admin CyberMail account connections |
|
||||
| `cybermail_domains` | Tracks sending domains and their verification status |
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Step 1: Access CyberMail
|
||||
|
||||
Navigate to: **https://your-server:8090/emailDelivery/**
|
||||
|
||||
You'll see the CyberMail marketing page with plan information and a "Get Started Free" button.
|
||||
|
||||
### Step 2: Connect Your Account
|
||||
|
||||
1. Click **"Get Started Free"**
|
||||
2. Enter your email address (defaults to your CyberPanel admin email)
|
||||
3. Create a password for your CyberMail account
|
||||
4. Click **Connect**
|
||||
|
||||
This registers your account on the CyberMail platform and obtains an API key that's stored locally for future API calls.
|
||||
|
||||
> **Note**: If you already have a CyberMail account on the platform, use the same email and password. The system will link your existing account.
|
||||
|
||||
### Step 3: Add Sending Domains
|
||||
|
||||
1. After connecting, you'll see the dashboard
|
||||
2. Go to the **Domains** tab
|
||||
3. Click **"Add Domain"**
|
||||
4. Enter your domain name (e.g., `example.com`)
|
||||
5. Click **Add**
|
||||
|
||||
The system will:
|
||||
- Register the domain on the CyberMail platform
|
||||
- Automatically create SPF, DKIM, and DMARC DNS records in PowerDNS
|
||||
- Report how many DNS records were configured
|
||||
|
||||
### Step 4: Verify Domain
|
||||
|
||||
1. Click **"Verify"** next to your domain
|
||||
2. The system checks SPF, DKIM, and DMARC records
|
||||
3. Green checkmarks appear for each verified record
|
||||
4. Status changes to "Verified" when all records pass
|
||||
|
||||
> **DNS Propagation**: If verification fails immediately after adding, wait 5-10 minutes for DNS propagation and try again.
|
||||
|
||||
### Step 5: Enable SMTP Relay (Optional)
|
||||
|
||||
The SMTP relay routes ALL outgoing email from your server through CyberMail:
|
||||
|
||||
1. Go to the **Relay** tab
|
||||
2. Click **"Enable Relay"**
|
||||
3. The system will:
|
||||
- Create (or rotate) SMTP credentials on the platform
|
||||
- Configure Postfix with the relay host (`mail.cyberpersons.com:587`)
|
||||
- Set up SASL authentication
|
||||
- Enable TLS encryption
|
||||
|
||||
**What gets configured in Postfix** (`/etc/postfix/main.cf`):
|
||||
```
|
||||
relayhost = [mail.cyberpersons.com]:587
|
||||
smtp_sasl_auth_enable = yes
|
||||
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
|
||||
smtp_sasl_security_options = noanonymous
|
||||
smtp_tls_security_level = encrypt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboard Overview
|
||||
|
||||
After connecting, the dashboard provides five tabs:
|
||||
|
||||
### Domains Tab
|
||||
- Lists all sending domains with verification status
|
||||
- SPF, DKIM, DMARC status badges (green = verified)
|
||||
- Actions: Verify, Auto-Configure DNS, Remove
|
||||
- DNS auto-configuration works when the domain exists in PowerDNS
|
||||
|
||||
### SMTP Tab
|
||||
- Manage SMTP credentials for sending
|
||||
- Create new credentials with descriptions
|
||||
- Rotate passwords (one-time display)
|
||||
- Delete unused credentials
|
||||
|
||||
### Relay Tab
|
||||
- Shows current relay status (Enabled/Disabled)
|
||||
- Displays relay host and port
|
||||
- Enable/Disable toggle
|
||||
- Relay info: `mail.cyberpersons.com:587` with STARTTLS
|
||||
|
||||
### Logs Tab
|
||||
- Paginated delivery logs
|
||||
- Filter by: Status (delivered/bounced/failed), Days (1-30)
|
||||
- Shows: Date, From, To, Subject, Status
|
||||
- Color-coded status badges
|
||||
|
||||
### Stats Tab
|
||||
- Aggregate stats: Total Sent, Delivered, Bounced, Failed, Delivery Rate
|
||||
- Per-domain breakdown table
|
||||
- Useful for identifying domains with deliverability issues
|
||||
|
||||
---
|
||||
|
||||
## Plans & Pricing
|
||||
|
||||
| Plan | Price | Emails/Month | Features |
|
||||
|------|-------|-------------|----------|
|
||||
| **Free** | $0 | 15,000 | Shared infrastructure, basic analytics |
|
||||
| **Starter** | $15/mo | 100,000 | Priority support, advanced analytics |
|
||||
| **Professional** | $90/mo | 500,000 | Dedicated IPs, custom DKIM, webhooks |
|
||||
| **Enterprise** | $299/mo | 2,000,000 | SLA guarantee, account manager, custom limits |
|
||||
|
||||
Upgrade at: https://platform.cyberpersons.com
|
||||
|
||||
---
|
||||
|
||||
## Promotional Banners
|
||||
|
||||
CyberMail banners appear on email-related pages to inform users about the delivery service:
|
||||
|
||||
- Mail Functions (`/mailServer/`)
|
||||
- Create Email Account
|
||||
- DKIM Manager
|
||||
- Webmail
|
||||
- Email Premium
|
||||
- Email Marketing
|
||||
|
||||
Banners are dismissible with a 7-day cookie-based suppression. They show:
|
||||
- "Stop Landing in Spam" headline
|
||||
- Brief feature description
|
||||
- "Get Started Free" CTA linking to `/emailDelivery/`
|
||||
|
||||
---
|
||||
|
||||
## Disconnecting
|
||||
|
||||
1. Go to **https://your-server:8090/emailDelivery/**
|
||||
2. Click the **"Disconnect"** button
|
||||
3. Confirm the action
|
||||
|
||||
Disconnecting will:
|
||||
- Disable SMTP relay if active (remove Postfix relay config)
|
||||
- Clear the stored API key
|
||||
- Remove local domain records
|
||||
- Reset SMTP credential references
|
||||
|
||||
> **Note**: Your CyberMail platform account is NOT deleted. You can reconnect later with the same credentials.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Account not connected" error
|
||||
The admin session doesn't have an active CyberMail connection. Click "Get Started Free" to connect.
|
||||
|
||||
### DNS records not auto-configured
|
||||
- The domain must exist in PowerDNS on this server
|
||||
- Check if the domain was created via CyberPanel's DNS management
|
||||
- If using external DNS, add records manually using the DNS records shown on the platform
|
||||
|
||||
### Domain verification failing
|
||||
- Wait 5-10 minutes after DNS changes for propagation
|
||||
- Verify records exist: `dig TXT example.com +short`
|
||||
- Check for conflicting SPF records (only one SPF record allowed per domain)
|
||||
|
||||
### SMTP relay not working
|
||||
- Check Postfix status: `systemctl status postfix`
|
||||
- Verify relay config: `grep relayhost /etc/postfix/main.cf`
|
||||
- Check SASL credentials: `cat /etc/postfix/sasl_passwd`
|
||||
- Test connectivity: `telnet mail.cyberpersons.com 587`
|
||||
- Check mail queue: `mailq`
|
||||
- View Postfix logs: `tail -f /var/log/mail.log`
|
||||
|
||||
### Relay shows "Failed to configure"
|
||||
- Ensure `/usr/local/CyberCP/plogical/mailUtilities.py` has the `configureRelayHost` method
|
||||
- Check file permissions on `/etc/postfix/sasl_passwd`
|
||||
- Verify Postfix is installed and running
|
||||
|
||||
### Emails still going to spam
|
||||
1. Verify all DNS records (SPF, DKIM, DMARC) are green
|
||||
2. Check your domain's reputation at https://www.mail-tester.com
|
||||
3. Ensure you're not sending to purchased/scraped lists
|
||||
4. Consider upgrading to a plan with dedicated IPs
|
||||
|
||||
---
|
||||
|
||||
## File Reference
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `emailDelivery/emailDeliveryManager.py` | Core business logic, platform API calls |
|
||||
| `emailDelivery/models.py` | Database models (CyberMailAccount, CyberMailDomain) |
|
||||
| `emailDelivery/views.py` | Django view functions (thin wrappers) |
|
||||
| `emailDelivery/urls.py` | URL routing (18 endpoints) |
|
||||
| `emailDelivery/static/emailDelivery/emailDelivery.js` | AngularJS controller |
|
||||
| `emailDelivery/templates/emailDelivery/index.html` | Single-page template (marketing + dashboard) |
|
||||
| `plogical/mailUtilities.py` | Postfix relay configuration (configureRelayHost/removeRelayHost) |
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- API keys are stored per-admin in the local database, never in config files
|
||||
- All platform API calls use HTTPS with Bearer token authentication
|
||||
- SMTP credentials use SASL over TLS (STARTTLS on port 587)
|
||||
- SASL password file is chmod 600 (root-only readable)
|
||||
- Session-based authentication with CSRF protection on all endpoints
|
||||
- Passwords are never stored locally — only on the platform
|
||||
393
docs/CYBERMAIL_TECHNICAL_REFERENCE.md
Normal file
393
docs/CYBERMAIL_TECHNICAL_REFERENCE.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# CyberMail Email Delivery — Technical Reference
|
||||
|
||||
**Module**: `emailDelivery`
|
||||
**Platform API Base**: `https://platform.cyberpersons.com/email/cp/`
|
||||
**Last Updated**: 2026-03-06
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
CyberPanel UI (AngularJS)
|
||||
|
|
||||
v
|
||||
Django Views (emailDelivery/views.py)
|
||||
|
|
||||
v
|
||||
EmailDeliveryManager (emailDelivery/emailDeliveryManager.py)
|
||||
|
|
||||
├──> CyberMail Platform API (HTTPS POST, Bearer auth)
|
||||
├──> PowerDNS (via dnsUtilities.DNS.createDNSRecord)
|
||||
└──> Postfix (via mailUtilities.py subprocess as root)
|
||||
```
|
||||
|
||||
### Design Patterns
|
||||
|
||||
- **Manager Class Pattern**: All business logic in `EmailDeliveryManager`, views are thin wrappers
|
||||
- **Per-User API Keys**: Each CyberPanel admin gets their own platform API key (no server-level key)
|
||||
- **AngularJS SPA**: Single template with conditional rendering based on `isConnected` state
|
||||
- **Subprocess for Root Operations**: Postfix relay config runs via `ProcessUtilities.outputExecutioner()` which executes as root
|
||||
|
||||
---
|
||||
|
||||
## Database Models
|
||||
|
||||
### CyberMailAccount (`cybermail_accounts`)
|
||||
|
||||
```python
|
||||
class CyberMailAccount(models.Model):
|
||||
admin = OneToOneField(Administrator, CASCADE) # 1:1 with admin
|
||||
platform_account_id = IntegerField(null=True) # Platform's account ID
|
||||
api_key = CharField(max_length=255) # Per-user Bearer token
|
||||
email = CharField(max_length=255) # Platform email
|
||||
plan_name = CharField(default='Free') # Display name
|
||||
plan_slug = CharField(default='free') # free/starter/professional/enterprise
|
||||
emails_per_month = IntegerField(default=15000) # Plan limit
|
||||
is_connected = BooleanField(default=False) # Active connection
|
||||
relay_enabled = BooleanField(default=False) # Postfix relay active
|
||||
smtp_credential_id = IntegerField(null=True) # Active relay credential
|
||||
smtp_username = CharField(max_length=255) # Relay SMTP username
|
||||
smtp_host = CharField(default='mail.cyberpersons.com')
|
||||
smtp_port = IntegerField(default=587)
|
||||
created_at = DateTimeField(auto_now_add=True)
|
||||
updated_at = DateTimeField(auto_now=True)
|
||||
```
|
||||
|
||||
### CyberMailDomain (`cybermail_domains`)
|
||||
|
||||
```python
|
||||
class CyberMailDomain(models.Model):
|
||||
account = ForeignKey(CyberMailAccount, CASCADE)
|
||||
domain = CharField(max_length=255)
|
||||
platform_domain_id = IntegerField(null=True)
|
||||
status = CharField(default='pending') # pending/verified
|
||||
spf_verified = BooleanField(default=False)
|
||||
dkim_verified = BooleanField(default=False)
|
||||
dmarc_verified = BooleanField(default=False)
|
||||
dns_configured = BooleanField(default=False) # Auto-configured in PowerDNS
|
||||
created_at = DateTimeField(auto_now_add=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API Endpoints (CyberPanel Internal)
|
||||
|
||||
All endpoints are POST, require authenticated CyberPanel session, and return JSON.
|
||||
|
||||
### Account Management
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/` | GET | Render page | — |
|
||||
| `/emailDelivery/connect/` | POST | Register/connect account | `{email, password}` |
|
||||
| `/emailDelivery/status/` | POST | Get account status + sync domains | — |
|
||||
| `/emailDelivery/disconnect/` | POST | Disconnect account, cleanup | — |
|
||||
|
||||
### Domain Management
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/domains/add/` | POST | Add sending domain | `{domain}` |
|
||||
| `/emailDelivery/domains/list/` | POST | List domains with status | — |
|
||||
| `/emailDelivery/domains/verify/` | POST | Verify DNS records | `{domain}` |
|
||||
| `/emailDelivery/domains/dns-records/` | POST | Get required DNS records | `{domain}` |
|
||||
| `/emailDelivery/domains/auto-configure-dns/` | POST | Auto-add DNS to PowerDNS | `{domain}` |
|
||||
| `/emailDelivery/domains/remove/` | POST | Remove sending domain | `{domain}` |
|
||||
|
||||
### SMTP Credentials
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/smtp/create/` | POST | Create SMTP credential | `{description}` |
|
||||
| `/emailDelivery/smtp/list/` | POST | List all credentials | — |
|
||||
| `/emailDelivery/smtp/rotate/` | POST | Rotate credential password | `{credential_id}` |
|
||||
| `/emailDelivery/smtp/delete/` | POST | Delete credential | `{credential_id}` |
|
||||
|
||||
### Relay
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/relay/enable/` | POST | Enable Postfix SMTP relay | — |
|
||||
| `/emailDelivery/relay/disable/` | POST | Disable Postfix SMTP relay | — |
|
||||
|
||||
### Analytics
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/stats/` | POST | Aggregate sending stats | — |
|
||||
| `/emailDelivery/stats/domains/` | POST | Per-domain stats | — |
|
||||
| `/emailDelivery/logs/` | POST | Paginated delivery logs | `{page, per_page, status, from_domain, days}` |
|
||||
|
||||
### Health
|
||||
|
||||
| Endpoint | Method | Purpose | Request Body |
|
||||
|----------|--------|---------|-------------|
|
||||
| `/emailDelivery/health/` | POST | Platform health check | — |
|
||||
|
||||
---
|
||||
|
||||
## Platform API Mapping
|
||||
|
||||
Each CyberPanel endpoint maps to a platform API call:
|
||||
|
||||
| CyberPanel Method | Platform Endpoint | Auth | Notes |
|
||||
|-------------------|-------------------|------|-------|
|
||||
| `connect()` | `api/register/` | None (public) | Returns `api_key` for future calls |
|
||||
| `getStatus()` | `api/account/` + `api/domains/list/` | Bearer | Syncs plan + domains |
|
||||
| `addDomain()` | `api/domains/add/` + `api/domains/dns-records/` | Bearer | Auto-configures DNS |
|
||||
| `listDomains()` | `api/domains/list/` | Bearer | Syncs verification status |
|
||||
| `verifyDomain()` | `api/domains/verify/` | Bearer | Returns spf/dkim/dmarc booleans |
|
||||
| `getDnsRecords()` | `api/domains/dns-records/` | Bearer | Returns required records |
|
||||
| `removeDomain()` | `api/domains/remove/` | Bearer | — |
|
||||
| `createSmtpCredential()` | `api/smtp/create/` | Bearer | Returns one-time password |
|
||||
| `listSmtpCredentials()` | `api/smtp/list/` | Bearer | Normalizes `id` → `credential_id` |
|
||||
| `rotateSmtpPassword()` | `api/smtp/rotate/` | Bearer | Normalizes `new_password` → `password` |
|
||||
| `deleteSmtpCredential()` | `api/smtp/delete/` | Bearer | Clears relay if active credential |
|
||||
| `enableRelay()` | `api/smtp/create/` or `api/smtp/rotate/` | Bearer | Then configures Postfix |
|
||||
| `getStats()` | `api/stats/` | Bearer | — |
|
||||
| `getDomainStats()` | `api/stats/domains/` | Bearer | Converts dict → array |
|
||||
| `getLogs()` | `api/logs/` | Bearer | Maps field names for JS |
|
||||
| `checkStatus()` | `api/health/` | None | — |
|
||||
|
||||
### API Response Normalization
|
||||
|
||||
The manager normalizes platform responses for frontend compatibility:
|
||||
|
||||
| Platform Field | CyberPanel Field | Method |
|
||||
|---------------|-----------------|--------|
|
||||
| `id` (credential) | `credential_id` | `listSmtpCredentials()` |
|
||||
| `new_password` | `password` | `rotateSmtpPassword()` |
|
||||
| `queued_at` | `date` | `getLogs()` |
|
||||
| `from_email` | `from` | `getLogs()` |
|
||||
| `to_email` | `to` | `getLogs()` |
|
||||
| `domains` (dict) | `domains` (array) | `getDomainStats()` |
|
||||
|
||||
---
|
||||
|
||||
## Connection Flow
|
||||
|
||||
```
|
||||
1. User clicks "Get Started Free"
|
||||
2. JS sends POST /emailDelivery/connect/ {email, password}
|
||||
3. Manager calls platform POST api/register/ (no auth)
|
||||
4. Platform returns {success, data: {api_key, account_id, plan_name, ...}}
|
||||
5. Manager creates/updates CyberMailAccount with api_key
|
||||
6. All subsequent calls use Authorization: Bearer <api_key>
|
||||
```
|
||||
|
||||
### Reconnection Behavior
|
||||
|
||||
When connecting with an existing `CyberMailAccount` record:
|
||||
- Updates email, api_key, platform_account_id, plan info
|
||||
- Resets: `smtp_credential_id=None`, `smtp_username=''`, `relay_enabled=False`
|
||||
- Deletes all local `CyberMailDomain` records (stale data)
|
||||
|
||||
### Disconnection Behavior
|
||||
|
||||
- Disables Postfix relay if active
|
||||
- Clears: `is_connected`, `relay_enabled`, `api_key`, `smtp_credential_id`, `smtp_username`, `platform_account_id`
|
||||
- Deletes all local domain records
|
||||
- Does NOT delete the platform account
|
||||
|
||||
---
|
||||
|
||||
## DNS Auto-Configuration
|
||||
|
||||
### Flow
|
||||
|
||||
```
|
||||
1. User adds domain via addDomain()
|
||||
2. Manager calls platform api/domains/add/
|
||||
3. Manager calls _autoConfigureDnsForDomain()
|
||||
4. → Finds domain zone in PowerDNS (dns.models.Domains)
|
||||
5. → Calls platform api/domains/dns-records/ to get required records
|
||||
6. → For each record: DNS.createDNSRecord(zone, host, type, value, priority, ttl)
|
||||
7. → Marks CyberMailDomain.dns_configured = True
|
||||
8. User clicks "Verify" → calls platform api/domains/verify/
|
||||
9. Platform checks DNS → returns spf/dkim/dmarc booleans
|
||||
```
|
||||
|
||||
### DNS Record Types Created
|
||||
|
||||
| Record | Type | Example Value |
|
||||
|--------|------|---------------|
|
||||
| SPF | TXT | `v=spf1 include:spf.cyberpersons.com ~all` |
|
||||
| DKIM | TXT | `v=DKIM1; k=rsa; p=MIIBIjANBg...` |
|
||||
| DMARC | TXT | `v=DMARC1; p=quarantine; rua=mailto:dmarc@...` |
|
||||
|
||||
### When Auto-Configuration Fails
|
||||
|
||||
- Domain not in PowerDNS → returns message to add records manually
|
||||
- Platform API unreachable → returns connection error
|
||||
- Individual record creation fails → logged, continues with remaining records
|
||||
|
||||
---
|
||||
|
||||
## SMTP Relay Configuration
|
||||
|
||||
### Enable Relay Flow
|
||||
|
||||
```
|
||||
1. Manager checks account.smtp_credential_id
|
||||
2. If no credential:
|
||||
→ POST api/smtp/create/ {email, description: "CyberPanel Relay"}
|
||||
→ Stores credential_id, username, gets one-time password
|
||||
3. If credential exists:
|
||||
→ POST api/smtp/rotate/ {email, credential_id}
|
||||
→ Gets new_password
|
||||
4. Calls subprocess: python mailUtilities.py configureRelayHost
|
||||
--smtpHost mail.cyberpersons.com --smtpPort 587
|
||||
--smtpUser <username> --smtpPassword <password>
|
||||
5. mailUtilities.py (runs as root):
|
||||
→ Writes /etc/postfix/main.cf relay lines
|
||||
→ Writes /etc/postfix/sasl_passwd
|
||||
→ chmod 600, postmap, systemctl reload postfix
|
||||
6. Sets account.relay_enabled = True
|
||||
```
|
||||
|
||||
### Postfix Configuration Applied
|
||||
|
||||
```ini
|
||||
# Added to /etc/postfix/main.cf
|
||||
relayhost = [mail.cyberpersons.com]:587
|
||||
smtp_sasl_auth_enable = yes
|
||||
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
|
||||
smtp_sasl_security_options = noanonymous
|
||||
smtp_tls_security_level = encrypt
|
||||
```
|
||||
|
||||
```
|
||||
# /etc/postfix/sasl_passwd
|
||||
[mail.cyberpersons.com]:587 username:password
|
||||
```
|
||||
|
||||
### Disable Relay
|
||||
|
||||
```
|
||||
1. Calls subprocess: python mailUtilities.py removeRelayHost
|
||||
2. mailUtilities.py removes relay lines from main.cf
|
||||
3. Restores smtp_tls_security_level = may
|
||||
4. Deletes sasl_passwd and .db files
|
||||
5. Reloads Postfix
|
||||
6. Sets account.relay_enabled = False
|
||||
```
|
||||
|
||||
### Output Parsing
|
||||
|
||||
The subprocess prints `1,None` on success. The manager checks for `'1,None' in output` (not `startswith`) because Python SyntaxWarnings may appear before the success output.
|
||||
|
||||
---
|
||||
|
||||
## Frontend Architecture
|
||||
|
||||
### Template: `emailDelivery/templates/emailDelivery/index.html`
|
||||
|
||||
- Extends `baseTemplate/index.html`
|
||||
- Uses AngularJS 1.6.5 with `{$ $}` interpolation (not `{{ }}`)
|
||||
- CSS classes use `ed-` prefix
|
||||
- Two views controlled by Django `{% if isConnected %}`:
|
||||
- Marketing landing page (not connected)
|
||||
- Dashboard with tabs (connected)
|
||||
|
||||
### Controller: `emailDeliveryCtrl`
|
||||
|
||||
Located in `emailDelivery/static/emailDelivery/emailDelivery.js`
|
||||
|
||||
Key state variables:
|
||||
```javascript
|
||||
$scope.isConnected // Boolean — dashboard vs marketing view
|
||||
$scope.activeTab // 'domains' | 'smtp' | 'relay' | 'logs' | 'stats'
|
||||
$scope.account // Account object from getStatus
|
||||
$scope.domains // Array of domain objects
|
||||
$scope.smtpCredentials // Array of SMTP credential objects
|
||||
$scope.stats // Aggregate stats object
|
||||
$scope.domainStats // Array of per-domain stats
|
||||
$scope.logs // Array of log entries
|
||||
$scope.logFilters // {status, from_domain, days}
|
||||
$scope.logsPage // Current log page number
|
||||
$scope.logsTotalPages // Total log pages
|
||||
```
|
||||
|
||||
### Modal Handling
|
||||
|
||||
Bootstrap 3 modals are placed OUTSIDE the `ng-controller` div (AngularJS scope limitation). Modal forms use jQuery + `onclick` handlers that call standalone functions (`cmConnect()`, `cmAddDomain()`, etc.) which make AJAX calls with `$.ajax()` and CSRF tokens.
|
||||
|
||||
### CSRF Token
|
||||
|
||||
All AJAX calls include the CSRF token from cookies:
|
||||
```javascript
|
||||
function getCookie(name) {
|
||||
var value = "; " + document.cookie;
|
||||
var parts = value.split("; " + name + "=");
|
||||
if (parts.length == 2) return parts.pop().split(";").shift();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### API Errors
|
||||
- Connection timeout: 30-second timeout on all platform API calls
|
||||
- Connection errors: caught and returned as `{success: false, error: "Could not connect..."}`
|
||||
- Missing API key: `{success: false, error: "No API key found. Please reconnect your account."}`
|
||||
|
||||
### Logging
|
||||
All errors logged via `CyberCPLogFileWriter.writeToFile()` with format:
|
||||
```
|
||||
[EmailDeliveryManager.<method>] Error: <message>
|
||||
```
|
||||
|
||||
Log file: `/home/cyberpanel/error-logs.txt`
|
||||
|
||||
---
|
||||
|
||||
## Banner System
|
||||
|
||||
Promotional banners appear on 6 email-related pages:
|
||||
|
||||
| Page | Template Path |
|
||||
|------|--------------|
|
||||
| Mail Functions | `mailServer/templates/mailServer/index.html` |
|
||||
| Create Email | `mailServer/templates/mailServer/createEmailAccount.html` |
|
||||
| DKIM Manager | `mailServer/templates/mailServer/dkimManager.html` |
|
||||
| Webmail | `webmail/templates/webmail/index.html` |
|
||||
| Email Premium | `emailPremium/templates/emailPremium/emailPage.html` |
|
||||
| Email Marketing | `emailMarketing/templates/emailMarketing/emailMarketing.html` |
|
||||
|
||||
### Banner Behavior
|
||||
- Hidden by default (`display:none`)
|
||||
- Shown via JS if `cybermail_dismiss=1` cookie is NOT present
|
||||
- Dismiss button sets cookie with 7-day expiry (`max-age=604800`)
|
||||
- Links to `/emailDelivery/`
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
emailDelivery/
|
||||
├── __init__.py
|
||||
├── apps.py # Django app config
|
||||
├── models.py # CyberMailAccount, CyberMailDomain
|
||||
├── views.py # Thin view wrappers (18 endpoints)
|
||||
├── urls.py # URL patterns
|
||||
├── emailDeliveryManager.py # Core business logic (~743 lines)
|
||||
├── migrations/
|
||||
│ └── __init__.py
|
||||
├── static/
|
||||
│ └── emailDelivery/
|
||||
│ └── emailDelivery.js # AngularJS controller
|
||||
└── templates/
|
||||
└── emailDelivery/
|
||||
└── index.html # SPA template (marketing + dashboard)
|
||||
```
|
||||
|
||||
### Related Files
|
||||
|
||||
| File | Modifications |
|
||||
|------|--------------|
|
||||
| `CyberCP/settings.py` | Added `'emailDelivery'` to `INSTALLED_APPS` |
|
||||
| `CyberCP/urls.py` | Added `path('emailDelivery/', include('emailDelivery.urls'))` |
|
||||
| `plogical/mailUtilities.py` | Added `configureRelayHost()` and `removeRelayHost()` static methods + argparse args |
|
||||
188
docs/CYBERMAIL_USER_GUIDE.md
Normal file
188
docs/CYBERMAIL_USER_GUIDE.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# CyberMail Email Delivery — User Guide
|
||||
|
||||
**For**: CyberPanel users and resellers
|
||||
**Last Updated**: 2026-03-06
|
||||
|
||||
---
|
||||
|
||||
## What is CyberMail?
|
||||
|
||||
CyberMail is CyberPanel's built-in email delivery service. It routes your outgoing emails through optimized servers so they land in the inbox instead of spam. Every CyberPanel installation includes CyberMail with a free tier of 15,000 emails per month.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Open CyberMail
|
||||
|
||||
Log into CyberPanel and navigate to: **Email > Email Delivery** or go directly to `https://your-server:8090/emailDelivery/`
|
||||
|
||||
### 2. Create Your Account
|
||||
|
||||
- Click **"Get Started Free"**
|
||||
- Enter your email address
|
||||
- Choose a password
|
||||
- Click **Connect**
|
||||
|
||||
You'll immediately get access to the dashboard with the Free plan (15,000 emails/month).
|
||||
|
||||
### 3. Add Your Domain
|
||||
|
||||
- Go to the **Domains** tab
|
||||
- Click **"Add Domain"**
|
||||
- Type your domain name (e.g., `mydomain.com`)
|
||||
- Click **Add**
|
||||
|
||||
CyberMail will automatically set up the DNS records needed for email delivery (SPF, DKIM, DMARC). If your domain's DNS is managed by CyberPanel's PowerDNS, this happens instantly.
|
||||
|
||||
### 4. Verify Your Domain
|
||||
|
||||
- Click **"Verify"** next to your domain
|
||||
- Check that SPF, DKIM, and DMARC all show green checkmarks
|
||||
- If any are red, wait a few minutes for DNS propagation and verify again
|
||||
|
||||
### 5. Start Sending
|
||||
|
||||
Once your domain is verified, emails sent from that domain will benefit from CyberMail's delivery optimization. For maximum deliverability, enable the SMTP relay.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Domain Management
|
||||
|
||||
Add multiple sending domains to your CyberMail account. Each domain gets:
|
||||
|
||||
- **SPF record** — tells receivers your emails are authorized
|
||||
- **DKIM signing** — cryptographically signs your emails to prevent tampering
|
||||
- **DMARC policy** — instructs receivers how to handle unauthenticated emails
|
||||
|
||||
**Status indicators:**
|
||||
- Gray badge = Not verified
|
||||
- Green badge = Verified and active
|
||||
|
||||
**Actions:**
|
||||
- **Verify** — recheck DNS records
|
||||
- **Auto DNS** — reconfigure DNS records in PowerDNS (if records were deleted)
|
||||
- **Remove** — remove the domain from CyberMail
|
||||
|
||||
### SMTP Credentials
|
||||
|
||||
Create credentials for sending emails through CyberMail's SMTP servers:
|
||||
|
||||
- **Create** — generates a username and one-time password
|
||||
- **Rotate** — generates a new password (old one stops working)
|
||||
- **Delete** — permanently removes the credential
|
||||
|
||||
> **Important**: The password is shown only once when created or rotated. Copy it immediately.
|
||||
|
||||
**SMTP Settings for manual configuration:**
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Host | `mail.cyberpersons.com` |
|
||||
| Port | `587` |
|
||||
| Security | STARTTLS |
|
||||
| Authentication | Login (SASL) |
|
||||
| Username | Shown after creation |
|
||||
| Password | Shown once after creation |
|
||||
|
||||
### SMTP Relay
|
||||
|
||||
The easiest way to use CyberMail — route ALL outgoing email from your server automatically:
|
||||
|
||||
- **Enable** — one click to configure everything
|
||||
- **Disable** — one click to revert to direct sending
|
||||
|
||||
When enabled, every email your server sends (from all websites, all email accounts) goes through CyberMail. No application-level changes needed.
|
||||
|
||||
### Delivery Logs
|
||||
|
||||
Monitor every email sent through CyberMail:
|
||||
|
||||
- **Filter by status**: All, Delivered, Bounced, Failed, Deferred
|
||||
- **Filter by time**: Last 1, 3, 7, 14, or 30 days
|
||||
- **View details**: Date, sender, recipient, subject, delivery status
|
||||
|
||||
### Statistics
|
||||
|
||||
Track your email performance:
|
||||
|
||||
- **Total Sent** — emails sent this billing period
|
||||
- **Delivered** — successfully delivered to recipient
|
||||
- **Bounced** — rejected by recipient server
|
||||
- **Failed** — permanent delivery failures
|
||||
- **Delivery Rate** — percentage of successful deliveries
|
||||
- **Per-Domain Breakdown** — stats for each sending domain
|
||||
|
||||
### Usage Tracking
|
||||
|
||||
The dashboard shows a progress bar of your monthly email usage:
|
||||
- Green = under 80% usage
|
||||
- Yellow/warning = approaching limit
|
||||
- An upgrade banner appears when you're near your plan limit
|
||||
|
||||
---
|
||||
|
||||
## Plans
|
||||
|
||||
| | Free | Starter | Professional | Enterprise |
|
||||
|---|---|---|---|---|
|
||||
| **Price** | $0/mo | $15/mo | $90/mo | $299/mo |
|
||||
| **Emails** | 15,000 | 100,000 | 500,000 | 2,000,000 |
|
||||
| **Infrastructure** | Shared | Shared | Dedicated IPs | Dedicated IPs |
|
||||
| **Analytics** | Basic | Advanced | Advanced | Advanced |
|
||||
| **Support** | Community | Priority | Priority | Dedicated Manager |
|
||||
| **Custom DKIM** | No | No | Yes | Yes |
|
||||
| **Webhooks** | No | No | Yes | Yes |
|
||||
| **SLA** | — | — | — | 99.9% |
|
||||
|
||||
To upgrade, visit the CyberMail platform at https://platform.cyberpersons.com
|
||||
|
||||
---
|
||||
|
||||
## Disconnecting Your Account
|
||||
|
||||
If you need to disconnect CyberMail:
|
||||
|
||||
1. Go to the CyberMail dashboard
|
||||
2. Click the **"Disconnect"** button
|
||||
3. Confirm the action
|
||||
|
||||
**What happens:**
|
||||
- SMTP relay is disabled (if it was enabled)
|
||||
- Postfix returns to direct sending
|
||||
- Local data (domains, credentials) is cleared
|
||||
- Your platform account is preserved — you can reconnect anytime
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Will enabling relay affect my existing email accounts?**
|
||||
A: Yes, ALL outgoing email from the server will route through CyberMail. This includes emails from websites (contact forms, notifications) and email accounts (Postfix). Incoming email is not affected.
|
||||
|
||||
**Q: Can I use CyberMail without the relay?**
|
||||
A: Yes. You can use SMTP credentials directly in your applications (WordPress SMTP plugins, custom scripts, etc.) without enabling the server-wide relay.
|
||||
|
||||
**Q: What happens if I exceed my plan limit?**
|
||||
A: Check with the platform for current overage policies. The dashboard shows your usage so you can monitor and upgrade before hitting limits.
|
||||
|
||||
**Q: Can I use CyberMail for bulk marketing emails?**
|
||||
A: CyberMail is designed for transactional and legitimate business email. Bulk marketing to purchased lists is not permitted. Use it for newsletters to opted-in subscribers, transactional emails, and business communications.
|
||||
|
||||
**Q: My domain DNS is not managed by CyberPanel. Can I still use CyberMail?**
|
||||
A: Yes. After adding the domain, click "DNS Records" to see the required records. Add them manually at your DNS provider (Cloudflare, Route53, etc.).
|
||||
|
||||
**Q: I disconnected and reconnected. Why are my old domains gone?**
|
||||
A: Reconnecting clears stale local data. Simply add your domains again — if they're still registered on the platform, they'll link back.
|
||||
|
||||
**Q: Is there a banner on other pages?**
|
||||
A: Yes, a promotional banner appears on email-related pages (Webmail, Mail Functions, etc.). It can be dismissed by clicking the X button and won't reappear for 7 days.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
- **CyberPanel Issues**: https://github.com/usmannasir/cyberpanel/issues
|
||||
- **CyberMail Platform**: https://platform.cyberpersons.com
|
||||
- **Email Deliverability Help**: Check your domain at https://www.mail-tester.com
|
||||
Reference in New Issue
Block a user