Exchange CatchAll Agent

A robust and feature-rich Transport Agent for Microsoft Exchange Server that implements comprehensive catchall email functionality with advanced logging, database integration, and security features.

🎉 What's New in v2.0.0: Major architecture overhaul with enhanced security, structured logging with correlation IDs, automatic memory management, thread-safe operations, and comprehensive input validation. See full changelog ⬇️

🌟 Key Features

• Universal Domain Redirection: Forward all emails sent to non-existent addresses to designated catchall addresses
• Flexible Matching: Support for both literal domain matching and powerful regex patterns
• Database Integration: Optional MySQL/MSSQL support for email logging and address blocking
• Enhanced Security: Comprehensive input validation, sanitization, and malformed email handling
• Structured Logging: Advanced logging with correlation IDs, structured data, and detailed error reporting
• Memory Management: Automatic cleanup mechanisms to prevent memory leaks
• Multi-Version Support: Compatible with Exchange 2007 SP3 through 2016 CU4
• Production Ready: Thread-safe implementation with comprehensive error handling

⚠️ Important: This agent only processes emails received from external mail servers. Internal email forwarding is not supported (#13).

📋 Prerequisites

• Microsoft Exchange Server (see supported versions)
• .NET Framework 3.5 (Exchange 2007/2010) or .NET 4.0+ (Exchange 2013/2016)
• Exchange Management Shell
• Administrator privileges
• Optional: MySQL Server or SQL Server (for advanced features)

🔧 Supported Versions

Exchange Version	Build Number	Framework	Status
Exchange 2007 SP3	8.3.*	.NET 3.5	✅ Supported
Exchange 2010	14.0.* - 14.3.*	.NET 3.5	✅ Supported
Exchange 2013	15.0.516.32 - 15.0.1497.18	.NET 4.0+	✅ Supported
Exchange 2016	15.1.225.17 - 15.1.669.32	.NET 4.0+	✅ Supported

📋 Complete Version List

Exchange 2010 Series

• Exchange 2010 (14.0.*)
• Exchange 2010 SP1 (14.1.*)
• Exchange 2010 SP2 (14.2.*)
• Exchange 2010 SP3 (14.3.*)

Exchange 2013 Series

• Exchange 2013 RTM (15.0.516.32)
• Exchange 2013 CU1-CU15 (15.0.620.29 - 15.0.1263.5)
• Exchange 2013 SP1 CU23 (15.0.1497.18)

Exchange 2016 Series

• Exchange 2016 Preview (15.1.225.17)
• Exchange 2016 RTM (15.1.225.42)
• Exchange 2016 CU1-CU4 (15.1.396.30 - 15.1.669.32)

🚀 Quick Start

Installation

1. Download and Extract

   # Download the latest release
   wget https://github.com/Pro/exchange-catchall/archive/master.zip
   # Extract to desired location (e.g., Desktop)
   

2. Database Setup (Optional)

   # For MySQL users - execute database.sql commands
   # Create tables and grant appropriate permissions
   # Modify connection strings as needed
   

3. Install Transport Agent

   # Open Exchange Management Shell as Administrator
   Set-ExecutionPolicy Unrestricted
   cd "C:\Path\To\ExtractedFolder"
   
   # Run the enhanced installation script
   .\install.ps1
   
   # Reset execution policy
   Set-ExecutionPolicy Restricted
   

4. Verify Installation

   # Check transport agent list
   Get-TransportAgent
   
   # Set appropriate priority (after antivirus, before other agents)
   Set-TransportAgent -Identity "Exchange CatchAll" -Priority 3
   

5. Monitor Event Logs

   • Create a custom view in Event Viewer
   • Filter by source: "Exchange CatchAll"
   • Monitor for any errors or warnings

💡 Tip: The installation script now includes comprehensive error handling with automatic rollback on failure.

Troubleshooting

Having installation issues? Check our troubleshooting guide for solutions.

⚙️ Configuration

The agent uses a comprehensive configuration system with enhanced validation and error handling.

Configuration Structure

• domainSection: Defines catchall domains with flexible matching rules
• customSection: Application settings including database integration and logging
• Validation: All configurations are validated at startup with detailed error reporting

⚠️ Important: Destination addresses must be handled by the local Exchange server (not external addresses)

Domain Configuration

Example Configuration

<domainSection>
  <Domains>
    <!-- Simple domain forwarding: Forward all mail to example.com to admin@company.org -->
    <Domain name="example.com" regex="false" address="admin@company.org"/>
    
    <!-- Advanced regex forwarding: *@subdomain.catchall.com -> subdomain@company.org -->
    <Domain name="^.*@(.*)\.catchall.com$" regex="true" address="$1@company.org"/>
    
    <!-- Plus addressing (sub-addressing): user+tag@domain.com -> user@domain.com -->
    <Domain name="^([^+]+)\+[^@]*@(.+)$" regex="true" address="$1@$2"/>
    
    <!-- Department-based forwarding: dept-*@company.com -> dept@company.com -->
    <Domain name="^([a-z]+)-.*@company\.com$" regex="true" address="$1@company.com"/>
    
    <!-- Year-based archive forwarding: *@archive2025.company.com -> archive@company.com -->
    <Domain name="^.*@archive\d{4}\.company\.com$" regex="true" address="archive@company.com"/>
  </Domains>
</domainSection>

<customSection>
  <!-- General Settings -->
  <general LogLevel="3" AddOrigToHeader="true" RejectIfBlocked="false"/>
  
  <!-- Database Integration (Optional) -->
  <database enabled="true" type="mysql" 
            connectionstrings="SERVER=localhost;PORT=3306;UID=catchall;PWD=catchall;DATABASE=catchall;"/>
</customSection>

Configuration Options

Section	Parameter	Values	Description
General	LogLevel	0-3	Logging verbosity (0=off, 1=error, 2=warn+error, 3=all)
	AddOrigToHeader	true/false	Add X-OrigTo header with original recipient
	RejectIfBlocked	true/false	Send 550 error for blocked addresses
Database	enabled	true/false	Enable database integration
	type	mysql/mssql	Database type
	connectionstrings	Connection string	Standard database connection string

Domain Matching Rules

1. Literal Matching: Exact domain comparison (case-insensitive)

   <Domain name="example.com" regex="false" address="admin@company.org"/>
   

2. Regex Matching: Pattern-based matching with capture groups

   <Domain name="^.*@(.*)\.catchall\.com$" regex="true" address="$1@company.org"/>
   

3. Advanced Regex Patterns:

   Plus Addressing (Sub-addressing)

   <!-- user+tag@domain.com -> user@domain.com -->
   <Domain name="^([^+]+)\+[^@]*@(.+)$" regex="true" address="$1@$2"/>
   

   • john+newsletter@company.com → john@company.com
   • support+ticket123@company.com → support@company.com
   • info+marketing@company.com → info@company.com

   Department-based Forwarding

   <!-- dept-anything@company.com -> dept@company.com -->
   <Domain name="^([a-z]+)-.*@company\.com$" regex="true" address="$1@company.com"/>
   

   • sales-lead@company.com → sales@company.com
   • support-urgent@company.com → support@company.com
   • hr-benefits@company.com → hr@company.com

   Archive/Year-based Forwarding

   <!-- *@archive2025.company.com -> archive@company.com -->
   <Domain name="^.*@archive\d{4}\.company\.com$" regex="true" address="archive@company.com"/>
   

   • data@archive2025.company.com → archive@company.com
   • backup@archive2024.company.com → archive@company.com

📊 Advanced Features

Structured Logging System

The agent includes a comprehensive logging system with:

• Correlation IDs: Track related log entries across the request lifecycle
• Structured Data: Key-value pairs for better log analysis
• Multiple Levels: Error, Warning, Information with configurable verbosity
• Fallback Logging: Automatic failover to System.Diagnostics.Trace

[A1B2C3D4] [2024-01-15 14:30:25.123 UTC] Email Forward: user@example.com -> admin@company.org
Properties:
  Domain: example.com
  DatabaseEnabled: true
  ProcessingTime: 2024-01-15T14:30:25.123Z
Thread: 12, Process: 2048

Database Integration

Enhanced database support with automatic input validation and sanitization:

Feature	MySQL	MSSQL	Description
Email Logging	✅	✅	Log all forwarded emails with metadata
Address Blocking	✅	✅	Block specific addresses with hit counting
Input Validation	✅	✅	RFC 5322 email validation
SQL Injection Protection	✅	✅	Parameterized queries
Connection Management	✅	✅	Automatic resource disposal

Security & Performance

• Memory Management: Automatic cleanup of expired tracking entries
• Thread Safety: Concurrent dictionary usage with proper locking
• Input Validation: Comprehensive RFC 5322 email address validation
• Regex Caching: Static compilation and caching for better performance
• Error Recovery: Graceful handling of malformed inputs and edge cases

🔄 Updates & Maintenance

Updating the Agent

# Simple update process
1. Download latest version
2. Run install.ps1 (automatically handles updates)
3. Verify installation with Get-TransportAgent

Migration Guides

🆕 Upgrading to v2.0.0 (Recommended)

v2.0.0 introduces major architectural improvements with backward compatibility:

• ✅ No Configuration Changes Required: Existing configurations work seamlessly
• ✅ Automatic Validation: Enhanced startup validation with detailed error reporting
• ✅ Improved Reliability: Better error handling and resource management
• ✅ Enhanced Security: Automatic input validation and sanitization
• ✅ Better Performance: Memory optimizations and regex caching

Upgrade Process:

# Simple upgrade - existing configs are preserved
1. Download v2.0.0
2. Run .\install.ps1 (automatically handles upgrade)
3. Verify with Get-TransportAgent
4. Check Event Log for enhanced structured logging

Legacy: Upgrading from v1.5.x to v1.6.0+

📋 Click to expand legacy migration steps

Configuration Update:

<!-- OLD FORMAT (v1.5.x) -->
<database enabled="true" type="mysql" host="localhost" port="3306" 
          database="catchall" user="catchall" password="catchall"/>

<!-- NEW FORMAT (v1.6.0+) -->
<database enabled="true" type="mysql" 
          connectionstrings="SERVER=localhost;PORT=3306;UID=catchall;PWD=catchall;DATABASE=catchall;"/>

Database Schema Update:

-- Fix table and column names
RENAME TABLE cought TO caught;
ALTER TABLE caught CHANGE idCought idCaught int(11) NOT NULL AUTO_INCREMENT;

🗑️ Uninstallation

# Simple uninstall process
.\uninstall.ps1

The uninstall script will:

• Remove the transport agent registration
• Clean up installed files
• Restore Exchange transport service
• Provide rollback on any failures

🛠️ Development Guide

Prerequisites for Development

Due to Microsoft licensing restrictions, Exchange DLLs cannot be redistributed. You must copy the following files from your Exchange installation:

📁 Source: C:\Program Files\Microsoft\Exchange Server\V14\Public\
├── Microsoft.Exchange.Data.Common.dll
├── Microsoft.Exchange.Data.Common.xml
├── Microsoft.Exchange.Data.Transport.dll
└── Microsoft.Exchange.Data.Transport.xml

📁 Destination: Lib/Exchange {VERSION}/

Build Process

# Build for specific Exchange version
msbuild CatchAllAgent.sln /p:Configuration="Ex2013"

# Debug build
msbuild CatchAllAgent.sln /p:Configuration="Debug Ex2013"

Remote Debugging Setup

1. Install Remote Debugging Tools on Exchange Server
2. Compile with Debug Information
3. Copy Debug DLL to Exchange Server
4. Attach to Process:

   Debug → Attach to Process → EdgeTransport.exe
   

Architecture Overview

• Multi-Version Support: Conditional compilation for different Exchange versions
• Thread Safety: ConcurrentDictionary and proper locking mechanisms
• Memory Management: Automatic cleanup timers and resource disposal
• Input Validation: RFC 5322 compliant email validation
• Error Handling: Comprehensive exception handling with structured logging

Contributing

We welcome contributions! Areas for improvement:

• Additional database connector implementations
• Enhanced regex pattern support
• Performance optimizations
• Extended Exchange version support

📈 Changelog

Version 2.0.0 (2025) - Major Architecture Overhaul 🚀

🔧 Enhanced Error Handling & Reliability

• Comprehensive PowerShell installation scripts with automatic rollback capability
• Prerequisites validation (Administrator check, Exchange Management Shell, service existence)
• Fail-fast configuration validation at startup with detailed error messages
• Database connection resource leak prevention with proper using statements

🛡️ Security & Input Validation

• RFC 5322 compliant email address validation with EmailValidator utility class
• Comprehensive input sanitization for database operations (control character removal, length limits)
• SQL injection prevention through parameterized queries and input validation
• Malformed email address detection and graceful error handling

📊 Structured Logging & Observability

• Thread-local correlation IDs for request tracking (RCPT-{hash} format)
• Structured logging with key-value properties and rich context data
• Email activity logging with domain, database status, and processing time
• Fallback logging to System.Diagnostics.Trace when EventLog fails
• Enhanced error messages with detailed context information

🚀 Performance & Memory Optimizations

• Static regex pattern caching in ConcurrentDictionary to prevent recompilation
• String concatenation optimization using string.Concat() and interpolation
• Email address normalization performed once per request with caching
• Automatic memory cleanup timer for tracking entries (15-min intervals, 30-min TTL)
• Thread-safe ConcurrentDictionary<string, (string[], DateTime)> with timestamp tracking

🔒 Thread Safety & Concurrency

• ConcurrentDictionary implementation for thread-safe message tracking
• Proper locking mechanisms in Logger class with lock statements
• Thread-safe regex compilation and caching across multiple instances
• Atomic operations for cleanup and resource management

✅ Architecture & Code Quality

• Comprehensive EmailValidator utility with RFC 5322 compliance
• Enhanced structured logging system with correlation ID support
• Proper resource disposal patterns with IDisposable implementation
• Configuration validation framework with startup error detection

Version History

📋 Click to view complete changelog

Version 1.7.0 (2022-05-22)

• ✅ Support for Exchange 2013 CU23

Version 1.6.9 (2016-12-22)

• ✅ Support for Exchange 2013 CU14, CU15 and 2016 CU4

Version 1.6.8 (2016-09-25)

• ✅ Support for Exchange 2016 CU3

Version 1.6.7 (2016-08-01)

• ✅ Support for Exchange 2013 SP1 CU13 & Exchange 2016 CU2

Version 1.6.6 (2016-04-24)

• 🔧 MySQL charset improvement: utf8mb4 for better Unicode support

Version 1.6.5 (2016-03-29)

• ✅ Support for Exchange 2013 SP1 CU11, CU12 & Exchange 2016 CU1

Version 1.6.4 (2015-11-01)

• ✅ Support for Exchange 2013 SP1 CU10 & Exchange 2016 RTM

Version 1.6.3 (2015-09-09)

• ✅ Support for all current Exchange versions
• 🔧 Install script now unlocks files (#8)

Version 1.6.2 (2014-03-11)

• 🐛 Fixed Issue #7 (Exchange 2013 Null Pointer if database disabled)

Version 1.6.0 (2014-03-10)

• ✅ Added MSSQL database support (Thanks to @AlexLaroche)
• 🐛 Fixed Issue #3 (Same message IDs in Dictionary for Orig-To Header)

Version 1.5.2 (2014-01-24)

• 🐛 Fixed database disable config evaluation
• ✅ Added additional supported Exchange versions (2007, 2010, 2013)

Version 1.5.1 (2013-11-27)

• ✅ Support for regex domains

Version 1.5.0 (2013-11-25)

• ✅ Added custom X-OrigTo header
• ✅ Added install and uninstall scripts
• ✅ Added build for all Exchange 2010 versions with different SPs

🤝 Support & Community

• 📝 Documentation: Check the CLAUDE.md for detailed development guidance
• 🐛 Issues: Report bugs and request features via GitHub Issues
• 🔧 Troubleshooting: See our troubleshooting guide
• 💡 Contributing: We welcome pull requests and contributions

📄 License

This project is licensed under the terms specified in the LICENSE file.

---

Based on the original work from: http://catchallagent.codeplex.com/

Developed with ❤️ for the Exchange Server community