hMailServer Data Export Automation

A comprehensive, professional-grade PowerShell 7 utility for extracting domains, accounts, aliases, and distribution lists from a local hMailServer instance. This tool supports multiple industrial-standard export formats, including CSV, JSON, Markdown, JavaScript, PHP, and XML, facilitating seamless integration with web applications, migration tools, and administrative dashboards.

📋 Table of Contents

1. Features
2. Prerequisites
3. Installation
4. Configuration
5. Usage
   • 5.1 Basic Syntax
   • 5.2 Export Formats
   • 5.3 Operation Modes
   • 5.4 Examples
6. How It Works
   • 6.1 COM Interface Integration
   • 6.2 Output Directory Resolution
   • 6.3 Advanced Logging (Mode B)
7. Troubleshooting
   • 7.1 Common Issues
   • 7.2 Debug Mode
8. Contributing
9. License
10. Acknowledgments
11. Author & Support

1. Features

• Multi-Format Export Support: Simultaneously export data to industrial formats: CSV, JSON, Markdown, JS, PHP, and XML.
• Comprehensive Data Retrieval: Extracts accounts, aliases, distribution lists, and list members with granular detail.
• Dynamic Directory Resolution: Intelligent three-tier priority system for managing output locations.
• Professional Logging: Detailed, color-coded console output with optional persistence to log files.
• Security-First Approach: Secure handling of hMailServer administrator credentials with interactive prompt support.
• Robust Error Handling: Built-in validation for COM object availability, write permissions, and filesystem paths.
• Automated Directory Management: Automatically verifies and creates target directories if they are missing.
• Advanced Mode (Mode B): Provides deep-dive extraction of distribution list members and full execution tracing.

2. Prerequisites

• Operating System: Windows (tested on Windows Server 2019/2022, Windows 10/11)
• PowerShell: Version 7.0 or higher (Cross-platform Core)
• hMailServer: Local installation with the COM API enabled (hMailServer.Application object)
• Permissions: Administrator rights on the local machine (to interact with hMailServer COM)
• Dependencies:
  • Access to the hMailServer Administrator password.
  • Write permissions to the target output directory.

3. Installation

3.1 Download the Script

Clone the repository to your local administrative workstation:

git clone https://github.com/paulmann/PowerShell_Export-hMailServerData.git
cd PowerShell_Export-hMailServerData

3.2 Verify Environment

Ensure that PowerShell 7 is active and that hMailServer service is running:

$PSVersionTable.PSVersion # Should be 7.x
Get-Service -Name hMailServer # Should be Running

4. Configuration

The script uses a prioritized configuration model. You can modify the variables at the top of Export-hMailServerData.ps1 for persistent settings.

4.1 Global Settings

$HMAILADMINUSER = "Administrator"
$OUTPUTDIR = "C:\Export" # Global fallback directory

4.2 Format-Specific Directories

You can direct different formats to different locations by setting specific variables:

$PHPOUTPUTDIR = "C:\Web\Includes"
$JSONOUTPUTDIR = "C:\App\Data"

4.3 Credentials

If $HMAILPASSWORD is left empty, the script will securely prompt for the password at runtime.

5. Usage

5.1 Basic Syntax

./Export-hMailServerData.ps1 [-ExportFormat <Format>] [-Mode <A|B>] [-OutputDir <Path>] [-DebugMode <0|1>]

5.2 Export Formats

Format	Extension	Use Case
CSV	.csv	Spreadsheet analysis / Bulk imports
JSON	.json	Web APIs / Modern application data
Markdown	.md	Documentation / GitHub Wiki content
JS	.js	JavaScript modules / Frontend integration
PHP	.php	PHP Constants / Backend inclusion
XML	.xml	Legacy systems / Structured data

5.2.1 Sample output: Accounts

All formats below show the same logical dataset: two example accounts from example.com with the exact field set produced by Get-DomainAccounts.[file:1]

Format	Sample output (excerpt)
CSV	Domain,Address,Active,IsAD,MaxSizeMB,PasswordExpirationEnabled,PasswordExpires,VacationMessageIsOn,ForwardEnabled,ForwardAddress,SignatureEnabled,AdminLevel,PersonFirstName,PersonLastName,Created,LastLogon example.com,user1@example.com,True,False,2048,False,,False,False,,False,0,John,Doe,2026-04-14T10:15:30Z,2026-04-14T11:00:00Z example.com,user2@example.com,True,False,1024,False,,False,False,,False,0,Jane,Doe,2026-04-14T10:16:02Z,2026-04-14T11:05:00Z
JSON	[ { "Domain": "example.com", "Address": "user1@example.com", "Active": true, "IsAD": false, "MaxSizeMB": 2048, "PasswordExpirationEnabled": false, "PasswordExpires": null, "VacationMessageIsOn": false, "ForwardEnabled": false, "ForwardAddress": null, "SignatureEnabled": false, "AdminLevel": 0, "PersonFirstName": "John", "PersonLastName": "Doe", "Created": "2026-04-14T10:15:30Z", "LastLogon": "2026-04-14T11:00:00Z" }, { "Domain": "example.com", "Address": "user2@example.com", "Active": true, "IsAD": false, "MaxSizeMB": 1024, "PasswordExpirationEnabled": false, "PasswordExpires": null, "VacationMessageIsOn": false, "ForwardEnabled": false, "ForwardAddress": null, "SignatureEnabled": false, "AdminLevel": 0, "PersonFirstName": "Jane", "PersonLastName": "Doe", "Created": "2026-04-14T10:16:02Z", "LastLogon": "2026-04-14T11:05:00Z" } ]
Markdown	Markdown export renders the same accounts dataset as a GitHub‑friendly table like the one you are reading now, with the exact same columns as in the CSV/JSON examples.
JS	/** * Auto-generated hMailServer export * Format: JavaScript Module */ const example_com_accounts = [ { Domain: "example.com", Address: "user1@example.com", Active: true, IsAD: false, MaxSizeMB: 2048, PasswordExpirationEnabled: false, PasswordExpires: null, VacationMessageIsOn: false, ForwardEnabled: false, ForwardAddress: null, SignatureEnabled: false, AdminLevel: 0, PersonFirstName: "John", PersonLastName: "Doe", Created: "2026-04-14T10:15:30Z", LastLogon: "2026-04-14T11:00:00Z" }, { Domain: "example.com", Address: "user2@example.com", Active: true, IsAD: false, MaxSizeMB: 1024, PasswordExpirationEnabled: false, PasswordExpires: null, VacationMessageIsOn: false, ForwardEnabled: false, ForwardAddress: null, SignatureEnabled: false, AdminLevel: 0, PersonFirstName: "Jane", PersonLastName: "Doe", Created: "2026-04-14T10:16:02Z", LastLogon: "2026-04-14T11:05:00Z" } ]; export default example_com_accounts;
PHP	<?php /** * Auto-generated hMailServer export * Format: PHP Constants */ const DATA_EXAMPLE_COM_ACCOUNTS = [ [ 'Domain' => 'example.com', 'Address' => 'user1@example.com', 'Active' => true, 'IsAD' => false, 'MaxSizeMB' => 2048, 'PasswordExpirationEnabled' => false, 'PasswordExpires' => null, 'VacationMessageIsOn' => false, 'ForwardEnabled' => false, 'ForwardAddress' => null, 'SignatureEnabled' => false, 'AdminLevel' => 0, 'PersonFirstName' => 'John', 'PersonLastName' => 'Doe', 'Created' => '2026-04-14T10:15:30Z', 'LastLogon' => '2026-04-14T11:00:00Z' ], [ 'Domain' => 'example.com', 'Address' => 'user2@example.com', 'Active' => true, 'IsAD' => false, 'MaxSizeMB' => 1024, 'PasswordExpirationEnabled' => false, 'PasswordExpires' => null, 'VacationMessageIsOn' => false, 'ForwardEnabled' => false, 'ForwardAddress' => null, 'SignatureEnabled' => false, 'AdminLevel' => 0, 'PersonFirstName' => 'Jane', 'PersonLastName' => 'Doe', 'Created' => '2026-04-14T10:16:02Z', 'LastLogon' => '2026-04-14T11:05:00Z' ], ]; return DATA_EXAMPLE_COM_ACCOUNTS;
XML	<?xml version="1.0" encoding="UTF-8"?> <export> <item> <Domain>example.com</Domain> <Address>user1@example.com</Address> <Active>1</Active> <IsAD>0</IsAD> <MaxSizeMB>2048</MaxSizeMB> <PasswordExpirationEnabled>0</PasswordExpirationEnabled> <PasswordExpires /> <VacationMessageIsOn>0</VacationMessageIsOn> <ForwardEnabled>0</ForwardEnabled> <ForwardAddress /> <SignatureEnabled>0</SignatureEnabled> <AdminLevel>0</AdminLevel> <PersonFirstName>John</PersonFirstName> <PersonLastName>Doe</PersonLastName> <Created>2026-04-14T10:15:30Z</Created> <LastLogon>2026-04-14T11:00:00Z</LastLogon> </item> <item> <Domain>example.com</Domain> <Address>user2@example.com</Address> <Active>1</Active> <IsAD>0</IsAD> <MaxSizeMB>1024</MaxSizeMB> <PasswordExpirationEnabled>0</PasswordExpirationEnabled> <PasswordExpires /> <VacationMessageIsOn>0</VacationMessageIsOn> <ForwardEnabled>0</ForwardEnabled> <ForwardAddress /> <SignatureEnabled>0</SignatureEnabled> <AdminLevel>0</AdminLevel> <PersonFirstName>Jane</PersonFirstName> <PersonLastName>Doe</PersonLastName> <Created>2026-04-14T10:16:02Z</Created> <LastLogon>2026-04-14T11:05:00Z</LastLogon> </item> </export>

5.2.2 Sample output: Aliases

This dataset matches the object shape returned by Get-DomainAliases (Domain, Name, Address, Value, Active, Created).[file:1]

Example aliases for example.com:

• sales@example.com → user1@example.com
• support@example.com → user2@example.com

Format	Sample output (excerpt)
CSV	Domain,Name,Address,Value,Active,Created example.com,sales,sales@example.com,user1@example.com,True,2026-04-14T10:20:00Z example.com,support,support@example.com,user2@example.com,True,2026-04-14T10:21:00Z
JSON	[ { "Domain": "example.com", "Name": "sales", "Address": "sales@example.com", "Value": "user1@example.com", "Active": true, "Created": "2026-04-14T10:20:00Z" }, { "Domain": "example.com", "Name": "support", "Address": "support@example.com", "Value": "user2@example.com", "Active": true, "Created": "2026-04-14T10:21:00Z" } ]
Markdown	Markdown export renders the same accounts dataset as a GitHub‑friendly table like the one you are reading now, with the exact same columns as in the CSV/JSON examples.
JS	const example_com_aliases = [ { Domain: "example.com", Name: "sales", Address: "sales@example.com", Value: "user1@example.com", Active: true, Created: "2026-04-14T10:20:00Z" }, { Domain: "example.com", Name: "support", Address: "support@example.com", Value: "user2@example.com", Active: true, Created: "2026-04-14T10:21:00Z" } ]; export default example_com_aliases;
PHP	const DATA_EXAMPLE_COM_ALIASES = [ ['Domain' => 'example.com', 'Name' => 'sales', 'Address' => 'sales@example.com', 'Value' => 'user1@example.com', 'Active' => true, 'Created' => '2026-04-14T10:20:00Z'], ['Domain' => 'example.com', 'Name' => 'support', 'Address' => 'support@example.com', 'Value' => 'user2@example.com', 'Active' => true, 'Created' => '2026-04-14T10:21:00Z'], ];
XML	<export> <item> <Domain>example.com</Domain> <Name>sales</Name> <Address>sales@example.com</Address> <Value>user1@example.com</Value> <Active>1</Active> <Created>2026-04-14T10:20:00Z</Created> </item> <item> <Domain>example.com</Domain> <Name>support</Name> <Address>support@example.com</Address> <Value>user2@example.com</Value> <Active>1</Active> <Created>2026-04-14T10:21:00Z</Created> </item> </export>

5.2.3 Sample output: Distribution list members

In advanced mode (Mode = 'B') the script also exports distribution list members using the shape returned by Get-DomainDistributionLists().Members (Domain, DistributionList, RecipientAddress).[file:1]

Example: list team@example.com with two recipients.

Format	Sample output (excerpt)
CSV	Domain,DistributionList,RecipientAddress example.com,team@example.com,user1@example.com example.com,team@example.com,user2@example.com
JSON	[ { "Domain": "example.com", "DistributionList": "team@example.com", "RecipientAddress": "user1@example.com" }, { "Domain": "example.com", "DistributionList": "team@example.com", "RecipientAddress": "user2@example.com" } ]
Markdown	Markdown export renders the same accounts dataset as a GitHub‑friendly table like the one you are reading now, with the exact same columns as in the CSV/JSON examples.
JS	const example_com_distribution_list_members = [ { Domain: "example.com", DistributionList: "team@example.com", RecipientAddress: "user1@example.com" }, { Domain: "example.com", DistributionList: "team@example.com", RecipientAddress: "user2@example.com" } ]; export default example_com_distribution_list_members;
PHP	const DATA_EXAMPLE_COM_DISTRIBUTION_LIST_MEMBERS = [ ['Domain' => 'example.com', 'DistributionList' => 'team@example.com', 'RecipientAddress' => 'user1@example.com'], ['Domain' => 'example.com', 'DistributionList' => 'team@example.com', 'RecipientAddress' => 'user2@example.com'], ];
XML	<export> <item> <Domain>example.com</Domain> <DistributionList>team@example.com</DistributionList> <RecipientAddress>user1@example.com</RecipientAddress> </item> <item> <Domain>example.com</Domain> <DistributionList>team@example.com</DistributionList> <RecipientAddress>user2@example.com</RecipientAddress> </item> </export>

5.3 Operation Modes

Mode	Level	Description
A	Standard	Primary data export (Accounts, Aliases, Lists)
B	Advanced	Includes DL members and detailed file logging

5.4 Examples

Standard JSON export to default directory:

./Export-hMailServerData.ps1 -ExportFormat JSON

Advanced PHP export with custom output path:

./Export-hMailServerData.ps1 -ExportFormat PHP -Mode B -OutputDir D:\Data

Markdown export with debug logging enabled:

./Export-hMailServerData.ps1 -ExportFormat Markdown -DebugMode 1

6. How It Works

6.1 COM Interface Integration

The script utilizes the hMailServer.Application COM object to communicate directly with the mail server engine. It performs authenticated sessions to traverse the object hierarchy:

1. Domains: Iterates through all hosted domains.
2. Accounts: Collects addresses, quotas, and signature states.
3. Aliases: Maps naming redirects.
4. Distribution Lists: Resolves list logic and (in Mode B) member relationships.

6.2 Output Directory Resolution

The script implements a strict three-tier priority logic to determine where files are saved:

1. Command Line: -OutputDir parameter (Highest priority).
2. Format Variable: e.g., $PHPOUTPUTDIR if set in the script.
3. Global Fallback: The $OUTPUTDIR variable.

6.3 Advanced Logging (Mode B)

When running in Mode B, the script generates a timestamped log file in the output directory. This log captures every step of the COM object interaction, providing a full audit trail for troubleshooting large-scale exports.

7. Troubleshooting

7.1 Common Issues

"Failed to create COM object":

• Ensure hMailServer is installed on the local machine.
• Verify the COM library is registered (run hMailServer Administrator once).

"Authentication Failed":

• Check that the $HMAILADMINUSER matches your admin login.
• Ensure the password entered (or in $HMAILPASSWORD) is correct.

"Write permission denied":

• Run PowerShell as Administrator.
• Verify the NTFS permissions on the target $OUTPUTDIR.

7.2 Debug Mode

Enable verbose output for deep inspection:

./Export-hMailServerData.ps1 -ExportFormat CSV -DebugMode 1

This provides:

• COM object lifecycle events.
• Domain-by-domain processing status.
• Serialization and filesystem IO details.

8. Contributing

Professional contributions are welcome! If you find a bug or have a feature request:

1. Fork the repository.
2. Create a feature branch.
3. Submit a Pull Request with a clear description of changes.

9. License

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

10. Acknowledgments

• hMailServer Team for providing a robust COM API for automation.
• PowerShell Community for the inspiration on modular script design.

11. Author & Support

Mikhail Deynekin

• 🌐 Website: deynekin.com
• 📧 Email: mid1977@gmail.com
• 🐙 GitHub: @paulmann

Getting Help

• 📖 Documentation: Read this README thoroughly.
• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Request features

---

Professional Note: Always verify your export results in a staging environment before integrating with production databases or web services.