# @serve.zone/mailer > Enterprise mail server with SMTP, HTTP API, and DNS management [![License](https://img.shields.io/badge/license-MIT-blue.svg)](license) [![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](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": "

World

" } ``` #### 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: '

This is a test email

', }); // 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: TTL: 3600 ``` ### SPF Record ``` Type: TXT Name: @ Value: v=spf1 mx ip4: ~all TTL: 3600 ``` ### DKIM Record ``` Type: TXT Name: default._domainkey Value: TTL: 3600 ``` ### DMARC Record ``` Type: TXT Name: _dmarc Value: v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com TTL: 3600 ``` Use `mailer dns setup ` 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/)