Rules API (for documentation)

Use this forum if you have problems with a hMailServer script, such as hMailServer WebAdmin or code in an event handler.
Post Reply
palinka
Senior user
Senior user
Posts: 3652
Joined: 2017-09-12 17:57

Rules API (for documentation)

Post by palinka » 2022-02-04 14:11

Dear Mods:

On another thread about COM scripting something, the request was made to update the documentation. I remembered I have some undocumented COM stuff for rules that should go in as well. Thanks in advance.

https://www.hmailserver.com/documentati ... bject_rule

Documentation references "RulesCriterias" and "RulesActions". Additionally, new pages should be made for "Criterias" and "Actions".

Criterias
UsePredefined = bool
PredefinedField = 0 - Unknown, 1 - From, 2 - To, 3 - CC, 4 - Subject, 5 - Body, 6 - MessageSize, 7 - RecipientList, 8 - DeliveryAttempts
HeaderField = string ("Custom Header Field")
MatchType = 0 - Unknown, 1 - Equals, 2 - Contains, 3 - LessThan, 4 - GreaterThan, 5 - RegExMatch, 6 - NotContains, 7 - NotEquals, 8 - Wildcard
MatchValue = string

Actions
Type = 0 - Unknown, 1 - DeleteEmail, 2 - ForwardEmail, 3 - Reply, 4 - MoveToImapFolder, 5 - RunScriptFunction, 6 - StopRuleProcessing, 7 - SetHeaderValue, 8 - SendUsingRoute, 9 - CreateCopy, 10 - BindToAddress


Here's an example in powershell if you want to add.

Code: Select all

<### Create Global Rule ###>

<# 
## Predefined Fields ##
0 - Unknown
1 - From
2 - To
3 - CC
4 - Subject
5 - Body
6 - MessageSize
7 - RecipientList
8 - DeliveryAttempts

## Search Type ##
0 - Unknown
1 - Equals
2 - Contains
3 - LessThan
4 - GreaterThan
5 - RegExMatch
6 - NotContains
7 - NotEquals
8 - Wildcard

## Rule Actions ##
0 - Unknown
1 - DeleteEmail
2 - ForwardEmail
3 - Reply
4 - MoveToImapFolder
5 - RunScriptFunction
6 - StopRuleProcessing
7 - SetHeaderValue
8 - SendUsingRoute
9 - CreateCopy
10 - BindToAddress
#>

<#  Add global rule  #>
$hMSAddRule = $hMS.Rules.Add()

$hMSAddRule.Name = "Test Rule"
$hMSAddRule.UseAND = $True
$hMSAddRule.Active = $True
$hMSAddRule.Save()
$hMSAddRule.MoveUp()

$hMSAddRuleCriteria = $hMSAddRule.Criterias.Add()
$hMSAddRuleCriteria.RuleID = $hMSAddRule.ID
$hMSAddRuleCriteria.UsePredefined = $True
$hMSAddRuleCriteria.PredefinedField = 7              #recipientList
$hMSAddRuleCriteria.MatchType = 6                    #not Contains
$hMSAddRuleCriteria.MatchValue = "spam@domain.com"
$hMSAddRuleCriteria.Save()

$hMSAddRuleCriteria2 = $hMSAddRule.Criterias.Add()
$hMSAddRuleCriteria2.RuleID = $hMSAddRule.ID
$hMSAddRuleCriteria2.UsePredefined = $True
$hMSAddRuleCriteria2.PredefinedField = 2             #To
$hMSAddRuleCriteria2.MatchType = 2                   #Contains
$hMSAddRuleCriteria2.MatchValue = "@domain.com"
$hMSAddRuleCriteria2.Save()

$hMSAddRuleCriteria3 = $hMSAddRule.Criterias.Add()
$hMSAddRuleCriteria3.RuleID = $hMSAddRule.ID
$hMSAddRuleCriteria3.UsePredefined = $False
$hMSAddRuleCriteria3.HeaderField = "X-hMailServer-Spam"
$hMSAddRuleCriteria3.MatchType = 1                   #Equals
$hMSAddRuleCriteria3.MatchValue = "YES"
$hMSAddRuleCriteria3.Save()        

$hMSAddRuleAction = $hMSAddRule.Actions.Add()
$hMSAddRuleAction.TO = "spam@test.com"
$hMSAddRuleAction.Type = 2
$hMSAddRuleAction.RuleID = $hMSAddRule.ID
$hMSAddRuleAction.Save()

$hMSAddRuleAction2 = $hMSAddRule.Actions.Add()
$hMSAddRuleAction2.Type = 1
$hMSAddRuleAction2.RuleID = $hMSAddRule.ID
$hMSAddRuleAction2.Save()

$hMSAddRule.Save()

User avatar
RvdH
Senior user
Senior user
Posts: 2316
Joined: 2008-06-27 14:42
Location: The Netherlands

Re: Rules API (for documentation)

Post by RvdH » 2022-02-04 18:55

While we're on it...

https://www.hmailserver.com/documentati ... e_antispam
Tarpitting
Tarpitting is an antispam technique that works by slowing down the communication with spammers
But Tarpitting feature is/was long gone in 5.6?, not?

FYI, it is removed in https://www.hmailserver.com/documentati ... e_antispam
Last edited by RvdH on 2022-02-04 19:07, edited 3 times in total.
CIDR to RegEx: d-fault.nl/cidrtoregex
DNS Lookup: d-fault.nl/dnstools
DKIM Generator: d-fault.nl/dkimgenerator
DNSBL Lookup: d-fault.nl/dnsbllookup
GEOIP Lookup: d-fault.nl/geoiplookup

User avatar
RvdH
Senior user
Senior user
Posts: 2316
Joined: 2008-06-27 14:42
Location: The Netherlands

Re: Rules API (for documentation)

Post by RvdH » 2022-02-04 18:59

https://www.hmailserver.com/documentati ... tails_ipv6

Maybe add a note for localhost to work with IPv6 you have to create a range similar to the "My computer" range, eg: "My computer (IPv6)" -> Lower IP -> ::1, Upper IP -> ::1
CIDR to RegEx: d-fault.nl/cidrtoregex
DNS Lookup: d-fault.nl/dnstools
DKIM Generator: d-fault.nl/dkimgenerator
DNSBL Lookup: d-fault.nl/dnsbllookup
GEOIP Lookup: d-fault.nl/geoiplookup

User avatar
katip
Senior user
Senior user
Posts: 1051
Joined: 2006-12-22 07:58
Location: Istanbul

Re: Rules API (for documentation)

Post by katip » 2022-02-04 19:08

once i had to create same set of rules for each user in our domain.
v4.4 documentation helped me a lot to write a script and do the job in one shot.
https://www.hmailserver.com/documentati ... om_objects
Katip
--
HMS 5.7, MariaDB 10.4.10, SA 3.4.4, ClamAV 0.103.5

User avatar
RvdH
Senior user
Senior user
Posts: 2316
Joined: 2008-06-27 14:42
Location: The Netherlands

Re: Rules API (for documentation)

Post by RvdH » 2022-02-04 19:14

CIDR to RegEx: d-fault.nl/cidrtoregex
DNS Lookup: d-fault.nl/dnstools
DKIM Generator: d-fault.nl/dkimgenerator
DNSBL Lookup: d-fault.nl/dnsbllookup
GEOIP Lookup: d-fault.nl/geoiplookup

palinka
Senior user
Senior user
Posts: 3652
Joined: 2017-09-12 17:57

Re: Rules API (for documentation)

Post by palinka » 2022-02-04 19:24

katip wrote:
2022-02-04 19:08
once i had to create same set of rules for each user in our domain.
v4.4 documentation helped me a lot to write a script and do the job in one shot.
https://www.hmailserver.com/documentati ... om_objects
I'll be damned... it was there all the time. Someone just needs to copy it over to "latest".

palinka
Senior user
Senior user
Posts: 3652
Joined: 2017-09-12 17:57

Re: Rules API (for documentation)

Post by palinka » 2022-02-04 19:27

I have not tested, but i wonder if Criterias is a synonym or replacement for RuleCriterias. I'll try it later when I have time.

User avatar
katip
Senior user
Senior user
Posts: 1051
Joined: 2006-12-22 07:58
Location: Istanbul

Re: Rules API (for documentation)

Post by katip » 2022-02-04 20:49

palinka wrote:
2022-02-04 19:27
I have not tested, but i wonder if Criterias is a synonym or replacement for RuleCriterias. I'll try it later when I have time.
something like this for one rule of my set:

Code: Select all

ruleExists = False
For c = 0 To oAccounts(i).Rules.Count -1
	If oAccounts(i).Rules(c).Name = "check_fwd" Then ruleExists = True
Next

If ruleExists = False Then

	Set oRuleAdd = oAccounts(i).Rules.Add
	oRuleAdd.Name = "check_fwd"
	oRuleAdd.UseAND = -1
	oRuleAdd.Active = 0
				
	Set oRuleCriteria = oRuleAdd.Criterias.Add
	oRuleCriteria.PredefinedField = 6 'size of message
	oRuleCriteria.MatchType = 4 'greater than
	oRuleCriteria.MatchValue = 0
	oRuleCriteria.Save
	
	Set oRuleAction = oRuleAdd.Actions.Add
	oRuleAction.Type =  7 'add header
	oRuleAction.HeaderName = "X-HMS-Forward"
	oRuleAction.Value = ""
	oRuleAction.Save
	
	Set oRuleAction = oRuleAdd.Actions.Add
	oRuleAction.Type =  5 'run a function
	oRuleAction.ScriptFunction = "GetSetFwdHeader"
	oRuleAction.Save
	
	oRuleAdd.Save			
	
End If
Katip
--
HMS 5.7, MariaDB 10.4.10, SA 3.4.4, ClamAV 0.103.5

palinka
Senior user
Senior user
Posts: 3652
Joined: 2017-09-12 17:57

Re: Rules API (for documentation)

Post by palinka » 2022-02-04 21:00

katip wrote:
2022-02-04 20:49
something like this for one rule of my set:

Code: Select all

...
	Set oRuleCriteria = oRuleAdd.Criterias.Add
...
	Set oRuleAction = oRuleAdd.Actions.Add
Right. You used the same as me. Maybe I got mine from you to begin with. I don't remember now. You used "Criterias" and "Actions" instead of what the documentation says: "RuleCriterias" and "RuleActions".

I'm wondering if "RuleCriterias" and "RuleActions" even exist anymore. That's what I want to test later.

Stoopid work always getting in the way of important stuff.

User avatar
mattg
Moderator
Moderator
Posts: 22038
Joined: 2007-06-14 05:12
Location: 'The Outback' Australia

Re: Rules API (for documentation)

Post by mattg » 2022-02-05 01:49

I think I am the only current regular forum user, other than Martin who can change any of this

I can only change the 'latest' documentation, not any of the versioned ones.
When a new version is released, the latest files are auto-copied and renamed to the version

The COM API changed SIGNIFICANTLY between 5.3 and 5.4, but also I think after 4.4, before 5.0 was released (hence the two sections for scripts in the forum)

I will look at these suggestions over the next couple of days, but please be VERY specific about the changes that you want. I'll be copying and pasting in all likelihood
Just 'cause I link to a page and say little else doesn't mean I am not being nice.
https://www.hmailserver.com/documentation

palinka
Senior user
Senior user
Posts: 3652
Joined: 2017-09-12 17:57

Re: Rules API (for documentation)

Post by palinka » 2022-02-05 21:33

I think the easiest think would be to copy from the old and add to the new. the new is missing most of the info. Just compare these pages:

RuleCriteria v4.4 vs latest
https://www.hmailserver.com/documentati ... lecriteria
https://www.hmailserver.com/documentati ... lecriteria

RuleAction v4.4 vs latest
https://www.hmailserver.com/documentati ... ruleaction
https://www.hmailserver.com/documentati ... ruleaction

Please be aware that my list of rule actions (which came from some thread on this board) is longer than that of the list on the v4.4 page.

v4.4 page:

Code: Select all

Property Type As eRuleActionType
The type of action:
Const eRADeleteEmail = 1, delete the email
Const eRAForwardEmail = 2, forward the email to another address
Const eRAReply = 3, reply to the sender of the email
Const eRAMoveToImapFolder = 4, move the message to an IMAP folder
Const eRAUnknown = 0, undefined behaviour (don't use)
palinka list:

Code: Select all

## Rule Actions ##
0 - Unknown
1 - DeleteEmail
2 - ForwardEmail
3 - Reply
4 - MoveToImapFolder
5 - RunScriptFunction
6 - StopRuleProcessing
7 - SetHeaderValue
8 - SendUsingRoute
9 - CreateCopy
10 - BindToAddress

Lastly, a scripting example already exists here: https://www.hmailserver.com/documentati ... e=com_rule :D

User avatar
mattg
Moderator
Moderator
Posts: 22038
Joined: 2007-06-14 05:12
Location: 'The Outback' Australia

Re: Rules API (for documentation)

Post by mattg » 2022-09-13 00:23

OK finally getting to these
palinka wrote:
2022-02-05 21:33
I think the easiest think would be to copy from the old and add to the new. the new is missing most of the info. Just compare these pages:

RuleCriteria v4.4 vs latest
https://www.hmailserver.com/documentati ... lecriteria
https://www.hmailserver.com/documentati ... lecriteria

RuleAction v4.4 vs latest
https://www.hmailserver.com/documentati ... ruleaction
https://www.hmailserver.com/documentati ... ruleaction
Done
Just 'cause I link to a page and say little else doesn't mean I am not being nice.
https://www.hmailserver.com/documentation

User avatar
mattg
Moderator
Moderator
Posts: 22038
Joined: 2007-06-14 05:12
Location: 'The Outback' Australia

Re: Rules API (for documentation)

Post by mattg » 2022-09-13 00:36

RvdH wrote:
2022-02-04 18:59
https://www.hmailserver.com/documentati ... tails_ipv6

Maybe add a note for localhost to work with IPv6 you have to create a range similar to the "My computer" range, eg: "My computer (IPv6)" -> Lower IP -> ::1, Upper IP -> ::1
Done
Just 'cause I link to a page and say little else doesn't mean I am not being nice.
https://www.hmailserver.com/documentation

Post Reply