Zetian 1.0.1

Zetian SMTP Server Library

A professional, high-performance SMTP server library for .NET with minimal dependencies. Build custom SMTP servers with ease using a fluent API and extensible architecture.

Features

• 🚀 High Performance: Built with System.IO.Pipelines for efficient I/O operations
• 🔒 Security: Full TLS/SSL support with STARTTLS
• 🔑 Authentication: Built-in PLAIN and LOGIN mechanisms, easily extensible
• 🛡️ Rate Limiting: Protect against abuse with configurable rate limits
• 📊 Event-Driven: Rich event system for message processing and monitoring
• 🔧 Extensible: Plugin architecture for custom authentication, filtering, and processing
• 📦 Minimal Dependencies: Only essential packages required
• 🎯 Multi-Framework: Supports .NET 6.0, 7.0, and 8.0

Installation

dotnet add package Zetian

Or via NuGet Package Manager:

Install-Package Zetian

Quick Start

Basic SMTP Server

using Zetian;

// Create and start a basic SMTP server
using var server = SmtpServerBuilder.CreateBasic();

server.MessageReceived += (sender, e) =>
{
    Console.WriteLine($"Received message from {e.Message.From}");
    Console.WriteLine($"Subject: {e.Message.Subject}");
};

await server.StartAsync();
Console.WriteLine($"Server running on {server.Endpoint}");

// Keep running...
Console.ReadKey();
await server.StopAsync();

Authenticated SMTP Server

using var server = new SmtpServerBuilder()
    .Port(587)
    .RequireAuthentication()
    .SimpleAuthentication("user", "password")
    .Build();

await server.StartAsync();

Secure SMTP Server with TLS

using var server = new SmtpServerBuilder()
    .Port(587)
    .Certificate("certificate.pfx", "password")
    .RequireSecureConnection()
    .Build();

await server.StartAsync();

Advanced Configuration

Using the Fluent Builder

var server = new SmtpServerBuilder()
    .Port(587)
    .BindTo(IPAddress.Any)
    .ServerName("My SMTP Server")
    .MaxMessageSizeMB(25)
    .MaxRecipients(100)
    .MaxConnections(50)
    .MaxConnectionsPerIP(5)
    
    // Security
    .Certificate(certificate)
    .RequireAuthentication()
    .RequireSecureConnection()
    
    // Authentication
    .AddAuthenticationMechanism("PLAIN")
    .AddAuthenticationMechanism("LOGIN")
    .AuthenticationHandler(async (username, password) =>
    {
        // Your authentication logic
        if (await ValidateUser(username, password))
            return AuthenticationResult.Succeed(username);
        return AuthenticationResult.Fail();
    })
    
    // Features
    .EnablePipelining()
    .Enable8BitMime()
    
    // Timeouts
    .ConnectionTimeout(TimeSpan.FromMinutes(5))
    .CommandTimeout(TimeSpan.FromSeconds(30))
    .DataTimeout(TimeSpan.FromMinutes(2))
    
    // Logging
    .LoggerFactory(loggerFactory)
    .EnableVerboseLogging()
    
    .Build();

Extensions

Rate Limiting

using Zetian.Extensions;
using Zetian.Extensions.RateLimiting;

server.AddRateLimiting(
    RateLimitConfiguration.PerHour(100)
);

Message Filtering

// Add spam filter
server.AddSpamFilter(new[] { "spam.com", "junk.org" });

// Add size filter (10MB max)
server.AddSizeFilter(10 * 1024 * 1024);

// Add custom filter
server.AddMessageFilter(message => 
{
    // Your filtering logic
    return !message.Subject?.Contains("SPAM") ?? true;
});

Message Storage

// Save messages to directory
server.SaveMessagesToDirectory(@"C:\smtp_messages");

// Custom message processing
server.MessageReceived += async (sender, e) =>
{
    // Save to database
    await SaveToDatabase(e.Message);
    
    // Forward to another service
    await ForwardMessage(e.Message);
    
    // Send notification
    await NotifyAdministrator(e.Message);
};

Domain Validation

// Only accept emails for specific domains
server.AddAllowedDomains("example.com", "mycompany.com");

// Custom recipient validation
server.AddRecipientValidation(recipient =>
{
    return IsValidRecipient(recipient.Address);
});

Event Handling

// Session events
server.SessionCreated += (s, e) =>
    Console.WriteLine($"New session from {e.Session.RemoteEndPoint}");

server.SessionCompleted += (s, e) =>
    Console.WriteLine($"Session completed: {e.Session.Id}");

// Message events
server.MessageReceived += (s, e) =>
{
    Console.WriteLine($"Message: {e.Message.Subject}");
    
    // Reject message if needed
    if (IsSpam(e.Message))
    {
        e.Cancel = true;
        e.Response = new SmtpResponse(550, "Message rejected as spam");
    }
};

// Error events
server.ErrorOccurred += (s, e) =>
    Console.WriteLine($"Error: {e.Exception.Message}");

Custom Authentication

// Register custom authenticator
AuthenticatorFactory.Register("CUSTOM", () => 
    new CustomAuthenticator());

// Or use the authentication handler
server.AuthenticationHandler(async (username, password) =>
{
    // Check against database
    var user = await db.GetUser(username);
    if (user != null && VerifyPassword(password, user.PasswordHash))
    {
        return AuthenticationResult.Succeed(username);
    }
    return AuthenticationResult.Fail();
});

Message Processing

server.MessageReceived += async (sender, e) =>
{
    var message = e.Message;
    
    // Access message properties
    Console.WriteLine($"ID: {message.Id}");
    Console.WriteLine($"From: {message.From?.Address}");
    Console.WriteLine($"To: {string.Join(", ", message.Recipients)}");
    Console.WriteLine($"Subject: {message.Subject}");
    Console.WriteLine($"Size: {message.Size} bytes");
    Console.WriteLine($"Has Attachments: {message.HasAttachments}");
    Console.WriteLine($"Priority: {message.Priority}");
    
    // Access headers
    var messageId = message.GetHeader("Message-Id");
    var contentType = message.GetHeader("Content-Type");
    
    // Get message content
    var textBody = message.TextBody;
    var htmlBody = message.HtmlBody;
    
    // Save message
    await message.SaveToFileAsync($"{message.Id}.eml");
    
    // Get raw data
    var rawData = await message.GetRawDataAsync();
};

Examples

The examples directory contains comprehensive examples:

1. BasicExample - Simple SMTP server without authentication
2. AuthenticatedExample - SMTP server with authentication
3. SecureExample - SMTP server with TLS/SSL support
4. RateLimitedExample - SMTP server with rate limiting
5. MessageStorageExample - Saving messages to disk
6. CustomProcessingExample - Custom message processing and filtering
7. FullFeaturedExample - Complete SMTP server with all features

Performance

Zetian is built for high performance:

• Efficient async/await patterns throughout
• System.IO.Pipelines for optimal I/O operations
• Connection pooling and throttling
• Minimal memory allocations
• Configurable buffer sizes

Security Considerations

• Always use TLS/SSL in production environments
• Implement proper authentication mechanisms
• Configure rate limiting to prevent abuse
• Validate and sanitize all inputs
• Implement proper logging and monitoring
• Keep the library updated with latest security patches

Requirements

• .NET 6.0, 7.0, or 8.0
• Windows, Linux, or macOS

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please open an issue on GitHub or contact the maintainers.

Acknowledgments

Built with ❤️ using modern .NET technologies.