serve.zone/dcrouter
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
Philipp Kunz
2025-05-21 00:12:49 +00:00
parent 5c85188183
commit b1890f59ee
27 changed files with 2096 additions and 705 deletions
Download Patch File Download Diff File Expand all files Collapse all files

494
readme.example.md Normal file
View File

@ -0,0 +1,494 @@
# DCRouter Email Configuration Example
This document provides a comprehensive example of configuring the UnifiedEmailServer in DCRouter for various email routing scenarios.
## Basic Configuration
Here's a complete example of a email configuration for the UnifiedEmailServer:
```typescript
import { IEmailConfig, EmailProcessingMode, IDomainRule } from './ts/config/email.config.js';
const emailConfig: IEmailConfig = {
// Basic server settings
useEmail: true,
behindSmartProxy: false,
hostname: "mail.example.com",
ports: [25, 587, 465],
// Default processing settings
defaultMode: "forward" as EmailProcessingMode,
defaultServer: "smtp.internal-relay.example.com",
defaultPort: 25,
defaultTls: true,
// TLS configuration
tls: {
certPath: "/path/to/tls/certificate.pem",
keyPath: "/path/to/tls/key.pem",
caPath: "/path/to/tls/ca.pem",
minVersion: "TLSv1.2",
ciphers: "HIGH:!aNULL:!MD5:!RC4"
},
// Email size and connection limits
maxMessageSize: 25 * 1024 * 1024, // 25MB
// Authentication settings
auth: {
required: true,
methods: ["PLAIN", "LOGIN"],
users: [
{ username: "user1", password: "securepassword1" },
{ username: "user2", password: "securepassword2" }
]
},
// Domain routing rules
domainRules: [
// Process emails for your primary domain via MTA
{
pattern: "*@example.com",
mode: "mta" as EmailProcessingMode,
mtaOptions: {
domain: "example.com",
dkimSign: true,
dkimOptions: {
domainName: "example.com",
keySelector: "mail"
}
}
},
// Forward support emails to help desk
{
pattern: "*@support.example.com",
mode: "forward" as EmailProcessingMode,
target: {
server: "helpdesk.example.com",
port: 25,
useTls: true
}
},
// Scan marketing emails for content and attachments
{
pattern: "*@marketing.example.com",
mode: "process" as EmailProcessingMode,
contentScanning: true,
scanners: [
{
type: "attachment",
action: "reject",
blockedExtensions: [".exe", ".zip", ".js", ".vbs", ".bat"]
},
{
type: "spam",
threshold: 5.0,
action: "tag"
}
],
transformations: [
{
type: "addHeader",
header: "X-Scanned-By",
value: "DCRouter Content Scanner"
}
]
},
// Forward all other emails to a backup server
{
pattern: "*@*",
mode: "forward" as EmailProcessingMode,
target: {
server: "backup-smtp.example.com",
port: 587,
useTls: true
}
}
],
// Queue configuration
queue: {
storageType: "memory",
ttl: 86400000, // 24 hours
maxItems: 10000,
checkInterval: 60000 // 1 minute
},
// Template configuration
templateConfig: {
from: "noreply@example.com",
replyTo: "support@example.com",
footerHtml: "<p>This is an automated message from Example Inc.</p>",
footerText: "This is an automated message from Example Inc."
},
// IP warmup configuration
serverConfig: {
delivery: {
concurrency: 10,
rateLimit: {
rate: 100,
interval: 60000 // 1 minute
},
retries: {
max: 3,
delay: 300000, // 5 minutes
useBackoff: true
}
},
security: {
useDkim: true,
verifyDkim: true,
verifySpf: true,
verifyDmarc: true,
enforceDmarc: true,
useTls: true,
requireValidCerts: true,
securityLogLevel: "info",
checkIPReputation: true,
scanContent: true,
maliciousContentAction: "tag",
threatScoreThreshold: 7.0
}
}
};
```
## Initializing the UnifiedEmailServer
Here's how to initialize the UnifiedEmailServer with the configuration:
```typescript
import { UnifiedEmailServer, IUnifiedEmailServerOptions } from './ts/mail/routing/classes.unified.email.server.js';
// Convert EmailConfig to UnifiedEmailServerOptions
const serverOptions: IUnifiedEmailServerOptions = {
ports: emailConfig.ports || [25],
hostname: emailConfig.hostname || 'localhost',
banner: `${emailConfig.hostname} ESMTP DCRouter`,
// Authentication
auth: emailConfig.auth,
// TLS
tls: emailConfig.tls,
// Message limits
maxMessageSize: emailConfig.maxMessageSize || 10 * 1024 * 1024, // 10MB default
maxClients: 100,
// Domain routing
domainRules: emailConfig.domainRules || [],
defaultMode: emailConfig.defaultMode || 'forward',
defaultServer: emailConfig.defaultServer,
defaultPort: emailConfig.defaultPort,
defaultTls: emailConfig.defaultTls,
// Deliverability options
ipWarmupConfig: {
enabled: true,
ipAddresses: ['198.51.100.1', '198.51.100.2', '198.51.100.3'],
targetDomains: ['gmail.com', 'yahoo.com', 'outlook.com'],
allocationPolicy: 'balanced'
},
reputationMonitorConfig: {
enabled: true,
domains: ['example.com', 'marketing.example.com'],
alertThresholds: {
bounceRate: 0.05, // 5%
complaintRate: 0.001 // 0.1%
}
}
};
// Create and start the server
const emailServer = new UnifiedEmailServer(serverOptions);
emailServer.start().then(() => {
console.log('UnifiedEmailServer started successfully');
}).catch((error) => {
console.error('Failed to start UnifiedEmailServer:', error);
});
```
## Use Case Examples
### 1. Forwarding Email Gateway (SMTP Proxy)
Configure DCRouter to forward emails for specific domains to internal mail servers:
```typescript
const forwardingRules: IDomainRule[] = [
// Main corporate domain - forward to Exchange
{
pattern: "*@corp.example.com",
mode: "forward" as EmailProcessingMode,
target: {
server: "exchange.internal",
port: 25,
useTls: true
}
},
// Marketing domain - forward to Marketing mail server
{
pattern: "*@marketing.example.com",
mode: "forward" as EmailProcessingMode,
target: {
server: "marketing-mail.internal",
port: 25,
useTls: false
}
}
];
```
### 2. Outbound MTA with DKIM Signing and IP Warmup
Configure DCRouter as an outbound mail transfer agent with DKIM signing and IP warmup:
```typescript
// MTA configuration with DKIM signing
const mtaRule: IDomainRule = {
pattern: "*@outbound.example.com",
mode: "mta" as EmailProcessingMode,
mtaOptions: {
domain: "outbound.example.com",
dkimSign: true,
dkimOptions: {
domainName: "outbound.example.com",
keySelector: "mail2023"
}
}
};
// IP Warmup configuration
const ipWarmupConfig = {
enabled: true,
ipAddresses: ['203.0.113.1', '203.0.113.2'],
targetDomains: ['gmail.com', 'yahoo.com', 'hotmail.com', 'aol.com'],
allocationPolicy: 'progressive',
fallbackPercentage: 20
};
```
### 3. Content Scanning and Security Gateway
Configure DCRouter to scan emails for malicious content and enforce security policies:
```typescript
const securityRule: IDomainRule = {
pattern: "*@*",
mode: "process" as EmailProcessingMode,
contentScanning: true,
scanners: [
// Scan for malicious attachments
{
type: "attachment",
action: "reject",
blockedExtensions: [".exe", ".dll", ".bat", ".vbs", ".js", ".cmd", ".scr", ".com", ".pif"]
},
// Scan for spam
{
type: "spam",
threshold: 6.0,
action: "tag"
},
// Scan for viruses
{
type: "virus",
action: "reject"
}
],
transformations: [
// Add scanning headers
{
type: "addHeader",
header: "X-Security-Scanned",
value: "DCRouter Security Gateway"
}
]
};
// Configure security settings
const securityConfig = {
useDkim: true,
verifyDkim: true,
verifySpf: true,
verifyDmarc: true,
enforceDmarc: true,
checkIPReputation: true,
scanContent: true,
maliciousContentAction: "quarantine",
threatScoreThreshold: 5.0,
rejectHighRiskIPs: true,
securityLogLevel: "warn"
};
```
### 4. Multi-Tenant Email Server
Configure DCRouter to handle emails for multiple domains with different processing rules:
```typescript
const multiTenantRules: IDomainRule[] = [
// Tenant 1: Process locally
{
pattern: "*@tenant1.example.org",
mode: "mta" as EmailProcessingMode,
mtaOptions: {
domain: "tenant1.example.org",
dkimSign: true,
dkimOptions: {
domainName: "tenant1.example.org",
keySelector: "t1mail"
}
}
},
// Tenant 2: Forward to their server
{
pattern: "*@tenant2.example.org",
mode: "forward" as EmailProcessingMode,
target: {
server: "mail.tenant2.com",
port: 587,
useTls: true
}
},
// Tenant 3: Process with content scanning
{
pattern: "*@tenant3.example.org",
mode: "process" as EmailProcessingMode,
contentScanning: true,
scanners: [
{
type: "attachment",
action: "tag",
blockedExtensions: [".zip", ".rar", ".7z"]
}
]
}
];
```
## Using the Bounce Management System
DCRouter includes a sophisticated bounce management system. Here's how to use it:
```typescript
// Get an instance of the UnifiedEmailServer
const emailServer = new UnifiedEmailServer(serverOptions);
// Check if an email is on the suppression list
const isSuppressed = emailServer.isEmailSuppressed('user@example.com');
// Get suppression information
const suppressionInfo = emailServer.getSuppressionInfo('user@example.com');
if (suppressionInfo) {
console.log(`Suppressed due to: ${suppressionInfo.reason}`);
console.log(`Suppressed since: ${new Date(suppressionInfo.timestamp)}`);
if (suppressionInfo.expiresAt) {
console.log(`Suppression expires: ${new Date(suppressionInfo.expiresAt)}`);
} else {
console.log('Suppression is permanent');
}
}
// Add an email to the suppression list
emailServer.addToSuppressionList(
'problem-user@example.com',
'Manual suppression due to user request',
Date.now() + (30 * 24 * 60 * 60 * 1000) // Expires in 30 days
);
// Remove an email from the suppression list
emailServer.removeFromSuppressionList('reactivated-user@example.com');
// Get all suppressed emails
const suppressionList = emailServer.getSuppressionList();
console.log(`There are ${suppressionList.length} suppressed email addresses`);
```
## Using the IP Warmup System
DCRouter's IP warmup system helps gradually build sender reputation for new IP addresses:
```typescript
// Add a new IP to warmup
emailServer.addIPToWarmup('198.51.100.4');
// Get warmup status for all IPs
const warmupStatus = emailServer.getIPWarmupStatus();
console.log('IP Warmup Status:', warmupStatus);
// Get warmup status for a specific IP
const specificIPStatus = emailServer.getIPWarmupStatus('198.51.100.1');
console.log(`Warmup day: ${specificIPStatus.day}`);
console.log(`Daily limit: ${specificIPStatus.dailyLimit}`);
console.log(`Emails sent today: ${specificIPStatus.sentToday}`);
// Update IP metrics based on feedback from mailbox providers
emailServer.updateIPWarmupMetrics('198.51.100.1', {
openRate: 0.25, // 25% open rate
bounceRate: 0.02, // 2% bounce rate
complaintRate: 0.001 // 0.1% complaint rate
});
// Check if an IP can send more emails today
if (emailServer.canIPSendMoreToday('198.51.100.1')) {
console.log('IP can send more emails today');
} else {
console.log('IP has reached its daily sending limit');
}
// Change the IP allocation policy
emailServer.setIPAllocationPolicy('volume-based');
```
## Sender Reputation Monitoring
Monitor and manage your domain reputation with these features:
```typescript
// Add a domain to monitoring
emailServer.addDomainToMonitoring('newdomain.example.com');
// Get reputation data for a specific domain
const reputationData = emailServer.getDomainReputationData('example.com');
console.log(`Reputation score: ${reputationData.score}`);
console.log(`Bounce rate: ${reputationData.bounceRate}`);
console.log(`Complaint rate: ${reputationData.complaintRate}`);
// Get a summary of all domains
const summary = emailServer.getReputationSummary();
console.log('Domain reputation summary:', summary);
// Record a custom engagement event
emailServer.recordReputationEvent('example.com', {
type: 'open',
count: 15
});
```
## Updating Configuration at Runtime
DCRouter allows updating configurations dynamically without restarting:
```typescript
// Update domain rules
const newRules: IDomainRule[] = [
// New rules here
];
emailServer.updateDomainRules(newRules);
// Update server options
emailServer.updateOptions({
maxMessageSize: 50 * 1024 * 1024, // 50MB
maxClients: 200,
defaultServer: 'new-relay.example.com'
});
```
This example configuration covers a wide range of use cases from simple forwarding to advanced security scanning, IP warmup, and reputation management, showcasing DCRouter's versatility as an email routing and processing solution.