mailer/readme.md

# @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": "<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/)