🚀 simple-smtp-mailer

High-performance SMTP mailer with queue management and OAuth2 support

📋 Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• Usage
• Development
• Documentation
• Contributing
• License

✨ Features

🚀 High Performance

• Optimized C++ Implementation: Built for speed and efficiency
• Parallel Processing: Multi-threaded email queue processing
• Memory Efficient: Smart memory management and resource handling

📧 Advanced SMTP Support

• Full SMTP Protocol: Complete RFC compliance
• Multiple Encryption: STARTTLS, SSL, and unencrypted connections
• Authentication Methods: PLAIN, LOGIN, CRAM-MD5, and OAuth2
• Connection Pooling: Efficient connection reuse and management

🔐 OAuth2 Integration

• Google Service Accounts: Native Gmail API support
• Microsoft Graph: Office 365 and Outlook integration
• Secure Token Management: Automatic token refresh and storage
• Multiple Providers: Extensible authentication framework

📊 Queue Management

• Persistent Storage: Reliable email queuing with disk persistence
• Priority Handling: Configurable email priority levels
• Retry Logic: Intelligent retry with exponential backoff
• Dead Letter Queue: Failed email handling and analysis

🛡️ Security & Reliability

• SSL/TLS Support: Modern encryption standards
• Certificate Validation: Proper SSL certificate verification
• Input Sanitization: Protection against injection attacks
• Logging & Monitoring: Comprehensive audit trails

📊 Advanced Logging

• JSON Logging: Structured, machine-readable log output
• Event-Specific Logging: Email events, API requests, SMTP operations
• Configurable Fields: Choose which fields to include in logs
• Custom Metadata: Add application-specific fields to all log entries
• Integration Ready: Compatible with ELK Stack, Splunk, Grafana
• Performance Optimized: Minimal overhead for production use

🔄 Daemon Mode

• Background Processing: Run as a system daemon for continuous operation
• Queue Management: Automatic email queue processing in the background
• System Integration: Native systemd, launchd, and Windows Service support
• Signal Handling: Graceful shutdown and configuration reload support
• Process Management: PID file management and status checking
• Production Ready: Optimized for 24/7 operation

🚀 Quick Start

Prerequisites

• macOS: Big Sur 11.0+ or later
• Linux: Ubuntu 20.04+, CentOS 8+, or compatible distributions
• C++ Compiler: GCC 9+ or Clang 12+
• CMake: 3.16 or later

Quick Installation

macOS

# Clone the repository
git clone https://github.com/blburns/simple-smtp-mailer.git
cd simple-smtp-mailer

# Install dependencies
make deps

# Build with auto-detected architecture
make build-script

# Create installer package
make package-dmg

# Install (double-click the DMG or use installer)
sudo installer -pkg dist/simple-smtp-mailer-*.pkg -target /

Linux

# Clone the repository
git clone https://github.com/blburns/simple-smtp-mailer.git
cd simple-smtp-mailer

# Install dependencies
make deps

# Build
make build

# Create platform-specific package
make package

# Install
sudo make install

First Run

# Test installation
simple-smtp-mailer --version

# View help
simple-smtp-mailer --help

# Check configuration
simple-smtp-mailer --config-check

📦 Installation

Package Types

macOS

• DMG Package: Drag-and-drop installation with GUI
• PKG Installer: Native macOS installer with post-install scripts
• Universal Binary: Intel + Apple Silicon compatibility

Linux

• DEB Package: Debian/Ubuntu family distributions
• RPM Package: Red Hat/CentOS/Fedora distributions
• Generic TGZ: Arch, Alpine, Gentoo, and other distributions

Installation Methods

Automated Installation

# macOS - Smart auto-detection
make build-script && make package-dmg

# Linux - Smart OS detection
make build && make package

Manual Installation

# Build from source
make clean && make build

# Install to system
sudo make install

# Create custom package
make package-custom

Installation Paths

/usr/local/bin/simple-smtp-mailer          # Main executable
/usr/local/lib/libsimple-smtp-mailer.dylib # Shared library
/usr/local/include/simple-smtp-mailer/     # Header files
/etc/simple-smtp-mailer/                   # Configuration files
/var/log/simple-smtp-mailer/               # Log files

⚙️ Configuration

Main Configuration File

# /etc/simple-smtp-mailer/simple-smtp-mailer.conf

[General]
log_level = INFO
log_file = /var/log/simple-smtp-mailer/simple-smtp-mailer.log
max_log_size = 10
max_log_files = 5

# JSON Logging Configuration
json_logging_enabled = true
json_log_fields = timestamp,level,message,thread,component,event_type
json_log_pretty_print = false
json_log_timestamp_format = %Y-%m-%dT%H:%M:%S.%fZ

[SMTP]
default_server = smtp.gmail.com
default_port = 587
default_encryption = STARTTLS
connection_timeout = 30
auth_timeout = 10

[Queue]
max_queue_size = 1000
retry_delay = 60
max_retries = 3
process_interval = 5

[Security]
verify_ssl = true
min_tls_version = 1.2

OAuth2 Configuration

# /etc/simple-smtp-mailer/auth/auth.conf

[Service_Accounts]
google_service_account_file = /path/to/service-account.json
google_scopes = https://www.googleapis.com/auth/gmail.send

microsoft_tenant_id = your-tenant-id
microsoft_client_id = your-client-id
microsoft_client_secret = your-client-secret

Email Templates

# /etc/simple-smtp-mailer/templates/email.conf

[Templates]
welcome_subject = Welcome to our service
welcome_body = Thank you for joining our service!
notification_subject = Important notification
notification_body = You have an important notification.

💻 Usage

Command Line Interface

Basic Usage

# Send a simple email
simple-smtp-mailer send --to user@example.com --subject "Hello" --body "Message body"

# Send with attachments
simple-smtp-mailer send --to user@example.com --subject "Report" --body "See attached" --attach report.pdf

# Send to multiple recipients
simple-smtp-mailer send --to user1@example.com,user2@example.com --subject "Group message" --body "Hello everyone"

Daemon Mode

Run as a background daemon for continuous email processing:

# Start daemon
simple-smtp-mailer --daemon

# Check daemon status
simple-smtp-mailer --status

# Stop daemon
simple-smtp-mailer --stop

# Reload configuration
simple-smtp-mailer --reload

For complete daemon documentation, see Daemon Mode Guide.

Queue Management

# List queued emails
simple-smtp-mailer queue list

# Show failed emails
simple-smtp-mailer queue failed

# Retry failed emails
simple-smtp-mailer queue retry

# Clear queue
simple-smtp-mailer queue clear

Configuration Management

# Validate configuration
simple-smtp-mailer config validate

# Test SMTP connection
simple-smtp-mailer config test-connection

# Show current settings
simple-smtp-mailer config show

Programmatic Usage

C++ API

#include <simple-smtp-mailer/email.hpp>
#include <simple-smtp-mailer/mailer.hpp>

// Create email
    ssmtp_mailer::Email email;
email.setFrom("sender@example.com");
email.addTo("recipient@example.com");
email.setSubject("Test Email");
email.setBody("Hello from simple-smtp-mailer!");

// Send email
ssmtp_mailer::Mailer mailer;
    mailer.send(email);

Python Bindings (Future)

import ssmtp_mailer

# Create and send email
email = ssmtp_mailer.Email(
    from_addr="sender@example.com",
    to_addrs=["recipient@example.com"],
    subject="Python Test",
    body="Hello from Python!"
)

mailer = ssmtp_mailer.Mailer()
mailer.send(email)

JSON Logging

#include <simple-smtp-mailer/json_logger.hpp>

// Configure JSON logging
ssmtp_mailer::JsonLogConfig config;
config.enabled = true;
config.fields = "timestamp,level,message,thread,component,event_type";
config.custom_fields["service"] = "simple-smtp-mailer";
config.custom_fields["version"] = "0.2.0";

// Initialize logger
ssmtp_mailer::JsonLogger::initialize(config);
ssmtp_mailer::JsonLogger& logger = ssmtp_mailer::JsonLogger::getInstance();

// Log email events
logger.logEmailEvent(ssmtp_mailer::LogLevel::INFO, "sender@example.com", 
                    {"recipient@example.com"}, "Welcome Email", "sent", "msg-12345");

// Log API requests
logger.logApiRequest(ssmtp_mailer::LogLevel::INFO, "SendGrid", "/v3/mail/send", 
                    "POST", 200, 150);

// Structured logging
std::map<std::string, std::string> data = {
    {"component", "smtp_client"},
    {"action", "connect"},
    {"server", "smtp.example.com"}
};
logger.logStructured(ssmtp_mailer::LogLevel::DEBUG, data);

🛠️ Development

Building from Source

Prerequisites

# macOS
xcode-select --install
brew install cmake openssl jsoncpp curl

# Ubuntu/Debian
sudo apt update
sudo apt install build-essential cmake libssl-dev libjsoncpp-dev libcurl4-openssl-dev

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install cmake openssl-devel jsoncpp-devel libcurl-devel

Build Commands

# Clean build
make clean

# Debug build
make debug

# Release build
make release

# Build with tests
make build && make test

# Run comprehensive test suite (58 tests)
cd build && ./tests/simple-smtp-mailer-tests

# Build specific architecture (macOS)
make build-intel      # Intel only
make build-arm64      # Apple Silicon only
make build-universal  # Both architectures

Development Tools

# Code formatting
make format

# Style checking
make check-style

# Static analysis
make analyze

# Run tests
make test

# Run specific test suites
cd build && ./tests/simple-smtp-mailer-tests --gtest_filter="BasicFunctionalityTest.*"
cd build && ./tests/simple-smtp-mailer-tests --gtest_filter="*IntegrationTest.*"

# Build documentation
make docs

Project Structure

simple-smtp-mailer/
├── src/                    # Source code
│   ├── core/              # Core functionality
│   │   ├── auth/          # Authentication modules
│   │   ├── config/        # Configuration management
│   │   ├── logging/       # Logging system
│   │   ├── queue/         # Email queue management
│   │   └── smtp/          # SMTP client implementation
│   ├── email.cpp          # Email class implementation
│   ├── mailer.cpp         # Main mailer class
│   └── main.cpp           # Command-line interface
├── include/                # Header files
├── scripts/                # Build and installation scripts
├── docs/                   # Documentation
├── tests/                  # Google Test framework (58 tests, 7 suites)
├── CMakeLists.txt          # CMake configuration
└── Makefile                # Build automation

Testing

# Run all tests
make test

# Run specific test suite
make test-unit
make test-integration
make test-performance

# Generate coverage report
make coverage

📚 Documentation

Available Documentation

• Installation Guide: docs/installation/
• Configuration Reference: docs/configuration/
• API Documentation: docs/api/
• Development Guide: docs/development/

Building Documentation

# Generate API docs
make docs-api

# Build user manual
make docs-manual

# Create PDF documentation
make docs-pdf

🤝 Contributing

We welcome contributions! Here's how you can help:

Getting Started

1. Fork the repository
2. Clone your fork locally
3. Create a feature branch
4. Make your changes
5. Test thoroughly
6. Submit a pull request

Development Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass
• Follow commit message conventions

Code Style

• C++: Follow Google C++ Style Guide
• Naming: Use descriptive names and consistent conventions
• Comments: Document complex logic and public APIs
• Error Handling: Use proper error codes and logging

Testing Framework

The project uses Google Test (gtest) for comprehensive testing:

Test Suite Overview

• 68 tests across 8 test suites
• BasicFunctionalityTest: Core data structures and validation (12 tests)
• APIClientTest: API client factory and configuration (7 tests)
• ProviderIntegrationTest: Multi-provider testing (8 tests)
• HTTPClientTest: HTTP client functionality (8 tests)
• MailgunIntegrationTest: Mailgun API integration (7 tests)
• AmazonSESIntegrationTest: Amazon SES API integration (8 tests)
• SendGridIntegrationTest: SendGrid API integration (8 tests)
• JsonLoggingTest: JSON logging functionality (10 tests)

Running Tests

# Run all tests
cd build && ./tests/simple-smtp-mailer-tests

# Run specific test suite
cd build && ./tests/simple-smtp-mailer-tests --gtest_filter="BasicFunctionalityTest.*"

# Run with verbose output
cd build && ./tests/simple-smtp-mailer-tests --gtest_verbose

Test Coverage

• Unit Tests: Individual component testing with mocks
• Integration Tests: Multi-component interaction testing
• API Provider Tests: Provider-specific functionality testing
• Error Handling Tests: Comprehensive error scenario coverage

Testing Requirements

• Unit Tests: Required for all new functionality
• Integration Tests: For complex features
• Performance Tests: For performance-critical code
• Coverage: Maintain >80% test coverage

📄 License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• OpenSSL: For cryptographic functionality
• libcurl: For HTTP/HTTPS support
• jsoncpp: For JSON parsing and generation
• CMake: For build system management
• Contributors: All who have helped improve this project

📞 Support

Getting Help

• Documentation: Check the docs/ directory
• Issues: Report bugs on GitHub Issues
• Discussions: Join conversations on GitHub Discussions
• Wiki: Check the GitHub Wiki

Community

• GitHub: https://github.com/blburns/simple-smtp-mailer
• Issues: https://github.com/blburns/simple-smtp-mailer/issues
• Releases: https://github.com/blburns/simple-smtp-mailer/releases

---

Made with ❤️ by the simple-smtp-mailer community

If you find this project useful, please consider giving it a ⭐ on GitHub!