initial
This commit is contained in:
361
readme.md
Normal file
361
readme.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# @serve.zone/mailer
|
||||
|
||||
> Enterprise mail server with SMTP, HTTP API, and DNS management
|
||||
|
||||
[](license)
|
||||
[](package.json)
|
||||
|
||||
## Overview
|
||||
|
||||
`@serve.zone/mailer` is a comprehensive mail server solution built with Deno, featuring:
|
||||
|
||||
- **SMTP Server & Client** - Full-featured SMTP implementation for sending and receiving emails
|
||||
- **HTTP REST API** - Mailgun-compatible API for programmatic email management
|
||||
- **DNS Management** - Automatic DNS setup via Cloudflare API
|
||||
- **DKIM/SPF/DMARC** - Complete email authentication and security
|
||||
- **Daemon Service** - Systemd integration for production deployments
|
||||
- **CLI Interface** - Command-line management of all features
|
||||
|
||||
## Architecture
|
||||
|
||||
### Technology Stack
|
||||
|
||||
- **Runtime**: Deno (compiles to standalone binaries)
|
||||
- **Language**: TypeScript
|
||||
- **Distribution**: npm (via binary wrappers)
|
||||
- **Service**: systemd daemon
|
||||
- **DNS**: Cloudflare API integration
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
mailer/
|
||||
├── bin/ # npm binary wrappers
|
||||
├── scripts/ # Build scripts
|
||||
├── ts/ # TypeScript source
|
||||
│ ├── mail/ # Email implementation (ported from dcrouter)
|
||||
│ │ ├── core/ # Email classes, validation, templates
|
||||
│ │ ├── delivery/ # SMTP client/server, queues
|
||||
│ │ ├── routing/ # Email routing, domain config
|
||||
│ │ └── security/ # DKIM, SPF, DMARC
|
||||
│ ├── api/ # HTTP REST API (Mailgun-compatible)
|
||||
│ ├── dns/ # DNS management + Cloudflare
|
||||
│ ├── daemon/ # Systemd service management
|
||||
│ ├── config/ # Configuration system
|
||||
│ └── cli/ # Command-line interface
|
||||
├── test/ # Test suite
|
||||
├── deno.json # Deno configuration
|
||||
├── package.json # npm metadata
|
||||
└── mod.ts # Main entry point
|
||||
```
|
||||
|
||||
## Installation
|
||||
|
||||
### Via npm (recommended)
|
||||
|
||||
```bash
|
||||
npm install -g @serve.zone/mailer
|
||||
```
|
||||
|
||||
### From source
|
||||
|
||||
```bash
|
||||
git clone https://code.foss.global/serve.zone/mailer
|
||||
cd mailer
|
||||
deno task compile
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### CLI Commands
|
||||
|
||||
#### Service Management
|
||||
|
||||
```bash
|
||||
# Start the mailer daemon
|
||||
sudo mailer service start
|
||||
|
||||
# Stop the daemon
|
||||
sudo mailer service stop
|
||||
|
||||
# Restart the daemon
|
||||
sudo mailer service restart
|
||||
|
||||
# Check status
|
||||
mailer service status
|
||||
|
||||
# Enable systemd service
|
||||
sudo mailer service enable
|
||||
|
||||
# Disable systemd service
|
||||
sudo mailer service disable
|
||||
```
|
||||
|
||||
#### Domain Management
|
||||
|
||||
```bash
|
||||
# Add a domain
|
||||
mailer domain add example.com
|
||||
|
||||
# Remove a domain
|
||||
mailer domain remove example.com
|
||||
|
||||
# List all domains
|
||||
mailer domain list
|
||||
```
|
||||
|
||||
#### DNS Management
|
||||
|
||||
```bash
|
||||
# Auto-configure DNS via Cloudflare
|
||||
mailer dns setup example.com
|
||||
|
||||
# Validate DNS configuration
|
||||
mailer dns validate example.com
|
||||
|
||||
# Show required DNS records
|
||||
mailer dns show example.com
|
||||
```
|
||||
|
||||
#### Sending Email
|
||||
|
||||
```bash
|
||||
# Send email via CLI
|
||||
mailer send \\
|
||||
--from sender@example.com \\
|
||||
--to recipient@example.com \\
|
||||
--subject "Hello" \\
|
||||
--text "World"
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
|
||||
```bash
|
||||
# Show current configuration
|
||||
mailer config show
|
||||
|
||||
# Set configuration value
|
||||
mailer config set smtpPort 25
|
||||
mailer config set apiPort 8080
|
||||
mailer config set hostname mail.example.com
|
||||
```
|
||||
|
||||
### HTTP API
|
||||
|
||||
The mailer provides a Mailgun-compatible REST API:
|
||||
|
||||
#### Send Email
|
||||
|
||||
```bash
|
||||
POST /v1/messages
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"from": "sender@example.com",
|
||||
"to": "recipient@example.com",
|
||||
"subject": "Hello",
|
||||
"text": "World",
|
||||
"html": "<p>World</p>"
|
||||
}
|
||||
```
|
||||
|
||||
#### List Domains
|
||||
|
||||
```bash
|
||||
GET /v1/domains
|
||||
```
|
||||
|
||||
#### Manage SMTP Credentials
|
||||
|
||||
```bash
|
||||
GET /v1/domains/:domain/credentials
|
||||
POST /v1/domains/:domain/credentials
|
||||
DELETE /v1/domains/:domain/credentials/:id
|
||||
```
|
||||
|
||||
#### Email Events
|
||||
|
||||
```bash
|
||||
GET /v1/events
|
||||
```
|
||||
|
||||
### Programmatic Usage
|
||||
|
||||
```typescript
|
||||
import { Email, SmtpClient } from '@serve.zone/mailer';
|
||||
|
||||
// Create an email
|
||||
const email = new Email({
|
||||
from: 'sender@example.com',
|
||||
to: 'recipient@example.com',
|
||||
subject: 'Hello from Mailer',
|
||||
text: 'This is a test email',
|
||||
html: '<p>This is a test email</p>',
|
||||
});
|
||||
|
||||
// Send via SMTP
|
||||
const client = new SmtpClient({
|
||||
host: 'smtp.example.com',
|
||||
port: 587,
|
||||
secure: true,
|
||||
auth: {
|
||||
user: 'username',
|
||||
pass: 'password',
|
||||
},
|
||||
});
|
||||
|
||||
await client.sendMail(email);
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration is stored in `~/.mailer/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"domains": [
|
||||
{
|
||||
"domain": "example.com",
|
||||
"dnsMode": "external-dns",
|
||||
"cloudflare": {
|
||||
"apiToken": "your-cloudflare-token"
|
||||
}
|
||||
}
|
||||
],
|
||||
"apiKeys": ["api-key-1", "api-key-2"],
|
||||
"smtpPort": 25,
|
||||
"apiPort": 8080,
|
||||
"hostname": "mail.example.com"
|
||||
}
|
||||
```
|
||||
|
||||
## DNS Setup
|
||||
|
||||
The mailer requires the following DNS records for each domain:
|
||||
|
||||
### MX Record
|
||||
```
|
||||
Type: MX
|
||||
Name: @
|
||||
Value: mail.example.com
|
||||
Priority: 10
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
### A Record
|
||||
```
|
||||
Type: A
|
||||
Name: mail
|
||||
Value: <your-server-ip>
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
### SPF Record
|
||||
```
|
||||
Type: TXT
|
||||
Name: @
|
||||
Value: v=spf1 mx ip4:<your-server-ip> ~all
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
### DKIM Record
|
||||
```
|
||||
Type: TXT
|
||||
Name: default._domainkey
|
||||
Value: <dkim-public-key>
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
### DMARC Record
|
||||
```
|
||||
Type: TXT
|
||||
Name: _dmarc
|
||||
Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com
|
||||
TTL: 3600
|
||||
```
|
||||
|
||||
Use `mailer dns setup <domain>` to automatically configure these via Cloudflare.
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Deno 1.40+
|
||||
- Node.js 14+ (for npm distribution)
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
# Compile for all platforms
|
||||
deno task compile
|
||||
|
||||
# Run in development mode
|
||||
deno task dev
|
||||
|
||||
# Run tests
|
||||
deno task test
|
||||
|
||||
# Format code
|
||||
deno task fmt
|
||||
|
||||
# Lint code
|
||||
deno task lint
|
||||
```
|
||||
|
||||
### Ported Components
|
||||
|
||||
The mail implementation is ported from [dcrouter](https://code.foss.global/serve.zone/dcrouter) and adapted for Deno:
|
||||
|
||||
- ✅ Email core (Email, EmailValidator, BounceManager, TemplateManager)
|
||||
- ✅ SMTP Server (with TLS support)
|
||||
- ✅ SMTP Client (with connection pooling)
|
||||
- ✅ Email routing and domain management
|
||||
- ✅ DKIM signing and verification
|
||||
- ✅ SPF and DMARC validation
|
||||
- ✅ Delivery queues and rate limiting
|
||||
|
||||
## Roadmap
|
||||
|
||||
### Phase 1 - Core Functionality (Current)
|
||||
- [x] Project structure and build system
|
||||
- [x] Port mail implementation from dcrouter
|
||||
- [x] CLI interface
|
||||
- [x] Configuration management
|
||||
- [x] DNS management basics
|
||||
- [ ] Cloudflare DNS integration
|
||||
- [ ] HTTP REST API implementation
|
||||
- [ ] Systemd service integration
|
||||
|
||||
### Phase 2 - Production Ready
|
||||
- [ ] Comprehensive testing
|
||||
- [ ] Documentation
|
||||
- [ ] Performance optimization
|
||||
- [ ] Security hardening
|
||||
- [ ] Monitoring and logging
|
||||
|
||||
### Phase 3 - Advanced Features
|
||||
- [ ] Webhook support
|
||||
- [ ] Email templates
|
||||
- [ ] Analytics and reporting
|
||||
- [ ] Multi-tenancy
|
||||
- [ ] Load balancing
|
||||
|
||||
## License
|
||||
|
||||
MIT © Serve Zone
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please see our [contributing guidelines](https://code.foss.global/serve.zone/mailer/contributing).
|
||||
|
||||
## Support
|
||||
|
||||
- Documentation: https://code.foss.global/serve.zone/mailer
|
||||
- Issues: https://code.foss.global/serve.zone/mailer/issues
|
||||
- Email: support@serve.zone
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- Mail implementation ported from [dcrouter](https://code.foss.global/serve.zone/dcrouter)
|
||||
- Inspired by [Mailgun](https://www.mailgun.com/) API design
|
||||
- Built with [Deno](https://deno.land/)
|
||||
Reference in New Issue
Block a user