hMailServer-Spam-Provisioner#

📋 Table of Contents#

🌟 Overview
🎯 Key Features
⚙️ How It Works
📥 Installation & Usage
🔧 Parameters
🔍 Debug Mode
🏢 Enterprise Deployment
🛡️ Security Considerations
🔧 Troubleshooting
🤝 Contributing
📄 License
🙏 Acknowledgments

🌟 Overview#

hMailServer-Spam-Provisioner is an idempotent PowerShell 7.5+ automation script that provisions spam management infrastructure across all active mailboxes in your hMailServer 5.x deployment.

For every active email account across all domains, the script automatically:

✉️ Creates a top-level IMAP folder [SPAM] (if not already present)
🔧 Creates an account-level filter rule "Spam -> [SPAM]" that moves spam messages based on:
- Header detection: X-hMailServer-Spam: YES
- Subject tagging: Subject contains [SPAM]

Idempotent by design — safe to re-run at any time. The script detects existing folders and rules, skipping them without modification or duplication.

Perfect for:

🚀 Initial hMailServer spam filter deployment
🔄 Bulk provisioning after adding new domains/accounts
✅ Audit and remediation (ensure all accounts have spam infrastructure)
🏗️ Infrastructure-as-Code for mail server configuration

🎯 Key Features#

✨ Idempotent Provisioning#

Zero-duplication guarantee: Detects existing folders and rules before creation
Safe re-execution: Run multiple times without breaking existing configuration
Audit-friendly: Clear console output showing what was created vs. already existed

🏗️ Enterprise-Ready Automation#

Bulk processing: Provisions all active accounts across all domains in one run
Configurable parameters: Customize folder names, tags, headers via command-line
Inactive account handling: Automatically skips disabled mailboxes
Comprehensive logging: Detailed console output with statistics and error tracking

🎨 Modern PowerShell Design#

PowerShell 7.5+ features: Leverages latest PSStyle for color-coded output
Secure credential handling: Password prompt with SecureString if not provided
COM API integration: Direct interaction with hMailServer 5.x COM interface
Type-safe enums: hMailServer field/match/action types defined as PowerShell enums

🐛 Debug Mode#

First-account testing: $DEBUG = 1 processes only the first active account
Verbose COM tracing: Shows all COM method invocations for troubleshooting
Safe development: Test logic without impacting entire mail server

📊 Detailed Reporting#

Domain-level summary: Visual breakdown by domain
Account-level details: Shows each account processed with outcomes
Statistics dashboard: Counts for domains, accounts, folders, rules created/existed
Error tracking: Highlights failures without stopping entire batch

⚙️ How It Works#

🔄 Technical Architecture#

graph TB
    START[Script Execution] --> INIT[Initialize Parameters]
    INIT --> PASS{Password Provided?}
    PASS -->|No| PROMPT[Secure Password Prompt]
    PASS -->|Yes| CONNECT[Connect to hMailServer COM API]
    PROMPT --> CONNECT
    
    CONNECT --> AUTH{Authenticate?}
    AUTH -->|Failed| ERROR1[Exit: Authentication Failed]
    AUTH -->|Success| MODE{Debug Mode?}
    
    MODE -->|DEBUG=1| DEBUG_INIT["Initialize Debug Mode<br/>First Active Account Only"]
    MODE -->|DEBUG=0| NORMAL_INIT["Initialize Normal Mode<br/>All Active Accounts"]
    
    DEBUG_INIT --> ITERATE_DOMAINS
    NORMAL_INIT --> ITERATE_DOMAINS
    
    ITERATE_DOMAINS[Iterate Through Domains] --> DOMAIN_HEADER[Display Domain Header]
    DOMAIN_HEADER --> ITERATE_ACCOUNTS[Iterate Through Accounts]
    
    ITERATE_ACCOUNTS --> ACTIVE_CHECK{Account Active?}
    ACTIVE_CHECK -->|No| SKIP[Skip: Display Inactive Message]
    ACTIVE_CHECK -->|Yes| DEBUG_CHECK["DEBUG Mode &<br/>Account Processed?"]
    
    DEBUG_CHECK -->|Yes| SUMMARY[Generate Summary]
    DEBUG_CHECK -->|No| ACCOUNT_HEADER[Display Account Header]
    
    ACCOUNT_HEADER --> FOLDER_CHECK{Folder Exists?}
    FOLDER_CHECK -->|Yes| FOLDER_EXISTS[Display: Folder Already Exists]
    FOLDER_CHECK -->|No| CREATE_FOLDER[Create IMAP Folder]
    
    CREATE_FOLDER --> FOLDER_SAVE["Save Folder<br/>ParentID=0 Top Level"]
    FOLDER_SAVE --> FOLDER_SUCCESS[Display: Folder Created]
    FOLDER_EXISTS --> RULE_CHECK
    FOLDER_SUCCESS --> RULE_CHECK
    
    RULE_CHECK{Rule Exists?} -->|Yes| RULE_EXISTS[Display: Rule Already Exists]
    RULE_CHECK -->|No| CREATE_RULE[Create Rule Object]
    
    CREATE_RULE --> RULE_CONFIG["Configure Rule:<br/>UseAND=false OR logic"]
    RULE_CONFIG --> ADD_CRIT1["Add Criterion 1:<br/>Header Match<br/>X-hMailServer-Spam: YES"]
    ADD_CRIT1 --> ADD_CRIT2["Add Criterion 2:<br/>Subject Contains<br/>[SPAM]"]
    ADD_CRIT2 --> ADD_ACTION1["Add Action 1:<br/>MoveToImapFolder<br/>[SPAM]"]
    ADD_ACTION1 --> ADD_ACTION2[Add Action 2:<br/>StopRuleProcessing]
    ADD_ACTION2 --> RULE_SAVE[Save Rule]
    RULE_SAVE --> RULE_SUCCESS[Display: Rule Created]
    
    RULE_EXISTS --> STATS_UPDATE
    RULE_SUCCESS --> STATS_UPDATE[Update Statistics]
    SKIP --> NEXT_ACCOUNT
    STATS_UPDATE --> NEXT_ACCOUNT{More Accounts?}
    
    NEXT_ACCOUNT -->|Yes| ITERATE_ACCOUNTS
    NEXT_ACCOUNT -->|No| NEXT_DOMAIN{More Domains?}
    
    NEXT_DOMAIN -->|Yes| ITERATE_DOMAINS
    NEXT_DOMAIN -->|No| SUMMARY
    
    SUMMARY[Display Summary Statistics] --> EXIT_CODE{Errors > 0?}
    EXIT_CODE -->|Yes| EXIT_FAIL[Exit Code: 1]
    EXIT_CODE -->|No| EXIT_SUCCESS[Exit Code: 0]
    
    %% Color scheme with explicit text color for contrast
    style START fill:#e3f2fd,color:#1a1a1a,stroke:#1976d2
    style CONNECT fill:#fff3e0,color:#1a1a1a,stroke:#f57c00
    style DEBUG_INIT fill:#ffe0b2,color:#1a1a1a,stroke:#ef6c00
    style NORMAL_INIT fill:#c8e6c9,color:#1a1a1a,stroke:#388e3c
    style CREATE_FOLDER fill:#b2dfdb,color:#1a1a1a,stroke:#00897b
    style CREATE_RULE fill:#b2ebf2,color:#1a1a1a,stroke:#00acc1
    style FOLDER_SUCCESS fill:#c8e6c9,color:#1a1a1a,stroke:#388e3c
    style RULE_SUCCESS fill:#c8e6c9,color:#1a1a1a,stroke:#388e3c
    style FOLDER_EXISTS fill:#e0e0e0,color:#1a1a1a,stroke:#616161
    style RULE_EXISTS fill:#e0e0e0,color:#1a1a1a,stroke:#616161
    style SKIP fill:#e0e0e0,color:#1a1a1a,stroke:#616161
    style ERROR1 fill:#ffcdd2,color:#1a1a1a,stroke:#c62828
    style EXIT_FAIL fill:#ffcdd2,color:#1a1a1a,stroke:#c62828
    style EXIT_SUCCESS fill:#c8e6c9,color:#1a1a1a,stroke:#388e3c
    style SUMMARY fill:#e1bee7,color:#1a1a1a,stroke:#7b1fa2

📥 Installation & Usage#

System Requirements#

PowerShell: Version 7.5 or higher (required for $PSStyle and modern COM interaction).
hMailServer: Version 5.x (tested on latest 5.4+ builds).
Permissions: Administrator privileges on the hMailServer host.
Access: Direct access to hMailServer COM API.

Installation#

Clone the repository:

git clone https://github.com/paulmann/hMailServer-Spam-Provisioner.git

Navigate to the script directory:
```
cd hMailServer-Spam-Provisioner
```

Usage Examples#

Standard Execution#

Prompts for the hMailServer administrator password securely:

.\hms-spam-provisioner.ps1

Automated Execution (CI/CD / Scheduled Tasks)#

Provide credentials via parameters:

.\hms-spam-provisioner.ps1 -AdminUser 'Administrator' -AdminPassword 'YourSecurePassword'

Custom Folder & Tags#

Provision with a custom IMAP folder name and subject tag:

.\hms-spam-provisioner.ps1 -SpamFolderName '[Junk]' -SpamSubjectTag '{SPAM}'

🔧 Parameters#

Parameter	Type	Default	Description
`AdminUser`	`string`	`Administrator`	hMailServer administrative username.
`AdminPassword`	`string`	Prompted	Password for the hMailServer administrator account.
`SpamFolderName`	`string`	`[SPAM]`	The name of the top-level IMAP folder to create.
`SpamSubjectTag`	`string`	`[SPAM]`	Subject tag to look for in the rule criteria.
`SpamHeaderField`	`string`	`X-hMailServer-Spam`	Custom header field name to match.
`SpamHeaderValue`	`string`	`YES`	Value of the header field that indicates spam.

🔍 Debug Mode#

The script includes a built-in safety mechanism for testing.
Set [int]$DEBUG = 1 at the top of the script (line 39) to:

Process ONLY the first active account found.
Enable Verbose COM tracing (outputs every method call to the console).
Stop execution immediately after the first account (or first error).

🏢 Enterprise Deployment#

For large-scale environments, this script can be integrated into your maintenance workflows:

Scheduled Maintenance#

Run the script weekly via Task Scheduler to ensure new accounts are always provisioned:

# Task action example
powershell.exe -ExecutionPolicy Bypass -File "C:\Scripts\hms-spam-provisioner.ps1" -AdminPassword '...'

Post-Migration Audit#

After migrating users to hMailServer, run this script to guarantee consistent spam management across the entire user base.

🛡️ Security Considerations#

Credential Handling: The script uses Read-Host -AsSecureString for password entry by default. Avoid hardcoding passwords in scripts; use environment variables or secret management modules in production.
Administrator Privileges: Requires elevation to interact with the hMailServer COM API.
Idempotency: Prevents configuration drift and prevents rule/folder duplication if the script is interrupted.

🔧 Troubleshooting#

"Failed to connect to COM API": Ensure hMailServer is installed on the local machine and the COM API is not disabled in hMailServer.INI.
"Authentication Failed": Verify the AdminUser and AdminPassword. Note that this is the hMailServer admin password, not the Windows admin password.
Permission Errors: Ensure you are running PowerShell as Administrator.

🤝 Contributing#

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository.
Create your feature branch (git checkout -b feature/AmazingFeature).
Commit your changes (git commit -m 'Add some AmazingFeature').
Push to the branch (git push origin feature/AmazingFeature).
Open a Pull Request.

📄 License#

This project is licensed under the PolyForm Noncommercial License 1.0.0 - see the LICENSE file for details.

🙏 Acknowledgments#

hMailServer Team: For providing a robust, free mail server with a powerful COM API.
PowerShell Community: For the continuous inspiration in infrastructure automation.

⭐ Star this repository if you find it useful for your hMailServer deployment!
Author: Mikhail Deynekin | GitHub
Version: 1.0.0 | Enterprise Ready