A comprehensive NestJS gateway for interacting with the WildDuck Email Server HTTP API. This gateway provides a clean, type-safe interface for managing email accounts, messages, mailboxes, and all other WildDuck features.

Features

Complete WildDuck API Coverage: All major WildDuck API endpoints are implemented
Type Safety: Full TypeScript support with comprehensive DTOs and interfaces
NestJS Best Practices: Follows enterprise-grade patterns and conventions
Modular Architecture: Clean separation of concerns with dedicated services
Swagger Documentation: Auto-generated API documentation
Error Handling: Robust error handling and logging
Observables: RxJS-based reactive programming for better async handling
Configuration: Environment-based configuration management

API Coverage

User Management

Create, read, update, delete users
User authentication and authorization
Password management and reset
User quota management
Authentication logs

Email Messages

List, search, and filter messages
Send, receive, and manage messages
Message attachments handling
Draft management
Message forwarding
Bulk operations

Mailboxes

Create and manage mail folders
Mailbox permissions and settings
Message counts and statistics
Mailbox retention policies

Email Addresses

Manage user email addresses and aliases
Primary address configuration
Address validation

Filters and Rules

Create email filters and rules
Automatic message processing
Spam filtering
Custom actions and conditions

Authentication & Security

Two-factor authentication (TOTP)
Application-specific passwords
Session management
Security logging

Advanced Features

Auto-replies and out-of-office messages
Message archiving and restoration
Audit trails and logging
Webhook integrations

Installation & Setup

1. Install Dependencies

This gateway is already integrated into your existing NestJS project. The required dependencies are:

npm install @nestjs/axios axios rxjs

2. Environment Configuration

Add the following environment variables to your .env file:

# WildDuck Mail Server Configuration
WILDDUCK_BASE_URL=http://localhost:8080
WILDDUCK_ACCESS_TOKEN=your-access-token-here
WILDDUCK_TIMEOUT=30000
WILDDUCK_RETRIES=3

3. Module Import

The MailServerModule is already imported in your AppModule. The gateway is ready to use!

Usage Examples

Basic User Operations

import { MailServerService } from "./modules/mail-server/services/mail-server.service";

@Injectable()
export class EmailService {
  constructor(private readonly mailServer: MailServerService) {}

  // Create a complete email account
  async createEmailAccount(username: string, password: string, email: string) {
    return this.mailServer
      .createEmailAccount({
        username,
        password,
        email,
        name: "User Name",
        quota: 1073741824, // 1GB
      })
      .toPromise();
  }

  // Authenticate user and get profile
  async authenticateUser(username: string, password: string) {
    return this.mailServer.authenticateAndGetUser(username, password).toPromise();
  }

  // Get user's mailboxes with message counts
  async getUserMailboxes(userId: string) {
    return this.mailServer.getUserMailboxes(userId).toPromise();
  }
}

Advanced Message Operations

// Search messages across all folders
async searchUserMessages(userId: string, query: string) {
  return this.mailServer.searchAllMessages(userId, query, 50).toPromise();
}

// Send a message
async sendMessage(userId: string, mailboxId: string, rawMessage: string) {
  return this.mailServer.sendMessage(userId, mailboxId, {
    raw: rawMessage,
    seen: false,
    flagged: false
  }).toPromise();
}

// Get recent messages
async getRecentMessages(userId: string, mailboxId: string) {
  return this.mailServer.getRecentMessages(userId, mailboxId, 20).toPromise();
}

Direct Service Access

For more granular control, you can access individual services directly:

@Injectable()
export class DetailedEmailService {
  constructor(private readonly mailServer: MailServerService) {}

  // Direct access to specific services
  async createUser(userData: CreateUserDto) {
    return this.mailServer.users.createUser(userData).toPromise();
  }

  async listMessages(userId: string, mailboxId: string, options: ListMessagesQueryDto) {
    return this.mailServer.messages.listMessages(userId, mailboxId, options).toPromise();
  }

  async createFilter(userId: string, filterData: CreateFilterDto) {
    return this.mailServer.filters.createFilter(userId, filterData).toPromise();
  }

  async setup2FA(userId: string, issuer: string) {
    return this.mailServer.auth.setup2FA(userId, { issuer }).toPromise();
  }
}

API Endpoints

The gateway exposes REST endpoints under /mail-server:

User Management

GET /mail-server/users - List users
POST /mail-server/users - Create user
GET /mail-server/users/:userId - Get user details
PUT /mail-server/users/:userId - Update user
DELETE /mail-server/users/:userId - Delete user

Authentication

POST /mail-server/authenticate - Authenticate user
POST /mail-server/users/:userId/2fa/totp/setup - Setup 2FA
POST /mail-server/users/:userId/2fa/totp/enable - Enable 2FA

Messages

GET /mail-server/users/:userId/mailboxes/:mailboxId/messages - List messages
POST /mail-server/users/:userId/mailboxes/:mailboxId/messages - Upload message
GET /mail-server/users/:userId/search - Search messages
GET /mail-server/users/:userId/flagged - List flagged messages

Mailboxes

GET /mail-server/users/:userId/mailboxes - List mailboxes
POST /mail-server/users/:userId/mailboxes - Create mailbox
PUT /mail-server/users/:userId/mailboxes/:mailboxId - Update mailbox

High-Level Operations

POST /mail-server/accounts - Create complete email account
POST /mail-server/auth-and-profile - Authenticate and get profile
GET /mail-server/users/:userId/mailboxes-with-counts - Get mailboxes with counts

Architecture

The gateway follows a clean, modular architecture:

src/modules/mail-server/
├── dto/                          # Data Transfer Objects
│   ├── create-user.dto.ts
│   ├── update-user.dto.ts
│   ├── authenticate.dto.ts
│   ├── message.dto.ts
│   ├── mailbox.dto.ts
│   ├── address.dto.ts
│   └── filter.dto.ts
├── interfaces/                   # TypeScript interfaces
│   └── wildduck-response.interface.ts
├── services/                     # Service layer
│   ├── wildduck-base.service.ts     # Base HTTP service
│   ├── wildduck-users.service.ts    # User management
│   ├── wildduck-messages.service.ts # Message operations
│   ├── wildduck-mailboxes.service.ts # Mailbox management
│   ├── wildduck-addresses.service.ts # Address management
│   ├── wildduck-auth.service.ts     # Authentication
│   ├── wildduck-filters.service.ts  # Filter management
│   └── mail-server.service.ts       # Main orchestrator
├── mail-server.controller.ts     # REST endpoints
└── mail-server.module.ts         # Module definition

Service Hierarchy

WildDuckBaseService: Provides common HTTP client functionality, error handling, and response processing
Specialized Services: Each service handles a specific domain (users, messages, etc.)
MailServerService: High-level service that orchestrates operations across multiple specialized services
MailServerController: REST API endpoints for external access

Error Handling

The gateway includes comprehensive error handling:

HTTP Errors: Automatic retry logic and timeout handling
WildDuck API Errors: Proper error parsing and re-throwing
Validation Errors: DTO validation with class-validator
Logging: Detailed logging for debugging and monitoring

Best Practices

Use High-Level Methods: Prefer MailServerService methods for common operations
Handle Observables: Convert to Promises with .toPromise() if needed
Error Handling: Always wrap calls in try-catch blocks
Type Safety: Use the provided DTOs for type safety
Environment Variables: Keep WildDuck credentials secure

Swagger Documentation

The gateway automatically generates Swagger documentation. Access it at:

Development: http://localhost:3000/api
Production: https://your-domain.com/api

Contributing

Follow the existing code patterns and architecture
Add proper TypeScript types and DTOs
Include comprehensive error handling
Add Swagger documentation for new endpoints
Write tests for new functionality

WildDuck Server Setup

This gateway requires a running WildDuck mail server. For setup instructions, visit:

License

This project follows the same license as your main application.