The COM API and Scripting

The COM API and Scripting

This page began as a chapter of the 6.2.10 manual and has been corrected for 6.2.24. The Control Panel's pages are grouped differently now, so the paths below use today's groups; the TLS ports 465, 993 and 995 exist only after you create them on the TCP/IP ports page (a fresh install seeds 25, 587, 110 and 143); and everything added since 6.2.10 is in Changes Since 6.2.10. Where a value here disagrees with the Settings Reference, which is generated from the code, the reference is right.

hMailServer exposes a full COM API. Anything the Control Panel can do, a script can do — it is the same interface.

From PowerShell

$app = New-Object -ComObject 'hMailServer.Application'
$app.Authenticate('Administrator', 'your-admin-password') | Out-Null

# Add a domain
$domain = $app.Domains.Add()
$domain.Name   = 'example.com'
$domain.Active = $true
$domain.Save()

# Add an account
$account = $domain.Accounts.Add()
$account.Address  = 'alice@example.com'
$account.Password = 'a-strong-password'
$account.Active   = $true
$account.MaxSize  = 1000          # MB, 0 = unlimited
$account.Save()

# Report on every mailbox
foreach ($d in $app.Domains) {
   foreach ($a in $d.Accounts) {
      '{0,-40} {1,8} MB used' -f $a.Address, [math]::Round($a.Size, 1)   # Size is already in MB
   }
}

If a second factor is enrolled on the administrator credential (Settings.EnrolAdministratorTOTP, 6.2.27), Authenticate refuses the administrator; call $app.AuthenticateWithCode('Administrator', $password, $code) instead, and read $app.AdministratorTOTPEnabled before authenticating to know whether a code is needed.

Authorization note. In 6.2.10 a real defect was fixed here: fifteen COM methods returned S_OK when they had actually refused the call, because they returned false from a function whose return type is HRESULT — and false is 0, which is S_OK. Five of them returned before writing their out-parameter, so an unauthorized caller got "success" plus uninitialized memory. If you script against the COM API, upgrade to 6.2.10 and make sure your scripts check return values.

Event scripts

Maintenance → Event scripts runs VBScript or JScript at defined points in the mail flow:

Event	Fires when
OnClientConnect	A client connects
OnHELO	The SMTP client has sent HELO/EHLO
OnClientLogon / OnClientValidatePassword	A client authenticates / a password is validated
OnSMTPData	The SMTP DATA phase begins
OnRecipientUnknown	A recipient is not known
OnAcceptMessage	A message is accepted
OnDeliverMessage	A message is about to be delivered
OnDeliveryFailed / OnDeliveryStart	Delivery outcome
OnError	An error is logged
OnExternalAccountDownload	Mail is fetched from an external account
OnBackupCompleted / OnBackupFailed	A backup finished / failed
OnTooManyInvalidCommands	A client has sent too many invalid commands

Sub OnAcceptMessage(oClient, oMessage)
   If InStr(LCase(oMessage.Subject), "urgent invoice") > 0 Then
      oMessage.HeaderValue("X-Suspicious") = "possible-invoice-fraud"
      oMessage.Save
   End If
End Sub

Event scripts run inside the mail flow. A slow script slows every message; a script that throws can stop delivery. Keep them short, and test on a non-production server.

---