About the Rule Component

Rules provide a mechanism so that you can manipulate messages in a Microsoft Exchange Information Store folder based on their contents or properties. For example, you can forward important messages containing specific text in the Subject field to a particular distribution list (DL) (for an introduction to rules, see About Rules). Rules created using the Rule component are server-side, and execute when messages or items are present in folders in the Microsoft Exchange Information Store.

To create a rule, you must create at least one Action and one Condition. When a message arrives that satisfies the Rule's condition, the actions are applied.

For example, suppose you want to delete any message that has the word "delete" in the Subject field. You create the following rule for the TestUser account on the Microsoft Exchange server SERVER:

const SUBSTRING      = 1             ' Substring
const IGNORECASE     = &H00010000    ' Ignore case
const ACTION_DELETE  = 3
const CdoPR_SUBJECT  = &H0037001E


' Create PropertyValue with delete in the Subject
Set objPropVal   = CreateObject("MSExchange.PropertyValue")
objPropVal.Tag   = CdoPR_SUBJECT
objPropVal.Value = "delete"

' Create ContentCondition
Set objContCond          = CreateObject("MSExchange.ContentCondition")
objContCond.PropertyType = CdoPR_SUBJECT
objContCond.Operator     = SUBSTRING + IGNORECASE
objContCond.Value        = objPropVal

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create Rule object
Set objRule        = CreateObject("MSExchange.Rule")
objRule.Name       = "Delete Test"
objRule.Condition  = objContCond
objRule.Actions.Add  ,objAction

' Create session object and logon to machine SERVER as TestUser
Set objCDOSess     = CreateObject("MAPI.Session")
objCDOSess.Logon  "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Create Rules object and add new Rule to Inbox rules
Set objRules      = CreateObject("MSExchange.Rules")
objRules.Folder  = objCDOSess.Inbox
objRules.Add       , objRule

' Update the rules
objRules.Update

objCDOSess.Logoff

Set objPropVal  = Nothing 
Set objContCond = Nothing 
Set objAction   = Nothing 
Set objRule     = Nothing 
Set objCDOSess  = Nothing 
Set objRules    = Nothing

Creating Actions

To create an action you set the two properties IAction::ActionType and IAction::Arg. Set the ActionType property to one of the enumerated types. These include:

Set the Arg property to match the requirements of the ActionType property. For example, if the ActionType is ACTION_FORWARD, the Arg property is a SAFEARRAY of BSTR values (array of strings) representing one or more addresses.

Here's an example of an action that moves messages to the "Deleted Items" folder.

const ACTION_MOVE  = 1   

Set objSession = CreateObject("MAPI.Session")
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Display all private folders
Set objInfoStore = objSession.InfoStores (2)
Set objPrivateFs = objInfoStore.RootFolder.Folders

For Each objFolder in objPrivateFs
  If objFolder.Name = "Deleted Items" Then
    ActionFolder = objFolder
    Exit For
  End If
Next

Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_MOVE
objAction.Arg        = ActionFolder
...

Here's an example of an action that forwards messages to the user Fred.

const CdoAddressListGAL  = 0             ' Global address list
const CdoAddressListPAB  = 1             ' Personal address book
const CdoPR_SEARCH_KEY   = &H300B0102

const ACTION_FORWARD     = 6

' Create the rules object
Set objRules = CreateObject("MSExchange.Rules")

' Create the CDO MAPI session
Set objSession = CreateObject("MAPI.Session")

' Logon to \\SERVER as TestUser
objSession.Logon   "","",False,True,True,True,"SERVER" & vbLF & "TestUser"

' Get the Rules collection on TestUser's Inbox
objRules.Folder = objSession.Inbox

' Get Address Entries for Global Address list (GAL)
Set objGAL = objSession.GetAddressList(CdoAddressListGAL)
Set objGALEntries = objGAL.AddressEntries

' Search for Fred
For Each objAddress In objGALEntries
  If objAddress.Name = "Fred" Then
    ActionAddressList(0) = ObjAddress.ID
    Exit For
  End If
Next

Set objAction = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_FORWARD
objAction.Arg        = ActionAddressList
...

Mapping Message Attributes to Conditions

This section describes how to determine what condition to use based on the attributes of a message. This section is not exhaustive. There are over 400 CDO properties of which perhaps 300 are properties that you might want to use in a condition. Therefore, this section discusses only the following message attributes:

• To or Cc
• From
• Subject
• Body
• Importance
• Sensitivity
• Attachments
• Sent Time
• Size

Identifying Messages Sent Directly to You in the To or Cc Field

Use the PropertyCondition object to identify messages based on whether your name appears in the To or Cc field.

• Set the IPropertyCondition::Operator property to 7 (REL_EQ) to identify messages that are to you or 5 (REL_NE) to identify messages that are not to you.
• Set the IPropertyCondition::PropertyTag property to &H0057000B (CdoPR_MESSAGE_TO_ME) for the To field, or &H0058000B (CdoPR_MESSAGE_CC_ME) for the Cc field.
• Set the related PropVal object's Tag property to the same CDO property as you did for the PropertyCondition object's PropertyTag property.

Here's an example of a rule that deletes messages where your name appears in the Cc line.

const CdoPR_MESSAGE_CC_ME = &H0058000B

const REL_EQ              = 7
const ACTION_DELETE       = 3

' Create the rules object
Set objRules = CreateObject("MSExchange.Rules")

' Set Property Value 
Set objPropVal   = CreateObject("MSExchange.PropertyValue")
objPropVal.Tag   = CdoPR_MESSAGE_CC_ME
objPropVal.Value = True

' Set Property Condition
Set objPropCond         = CreateObject("MSExchange.PropertyCondition")
objPropCond.Operator    = REL_EQ
objPropCond.PropertyTag = CdoPR_MESSAGE_CC_ME
objPropCond.Value       = objPropVal

' Set Action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Add Action and assign Condition
Set objRule         = CreateObject("MSExchange.Rule")
objRule.Name        = "Cc Test"
objRule.Actions.Add   , objAction
objRule.Condition   = objPropCond

' Create the CDO MAPI session
Set objSession = CreateObject("MAPI.Session")

' Logon to \\SERVER as TestUser
objSession.Logon   "","",False,True,True,True,"SERVER" & vbLF & "TestUser"

' Get the Rules on TestUser's Inbox
objRules.Folder = objSession.Inbox

' Add the rule
objRules.Add ,objRule

' Save the changes in the Information Store
objRules.Update

' Logoff the MAPI session
objSession.Logoff

' Relese the objects we created
Set objRules     = Nothing
Set objSession   = Nothing
Set objRule      = Nothing
Set objPropVal   = Nothing
Set objPropCond  = Nothing
Set objAction    = Nothing

Identifying Messages by Entries in the From Field

Use the CommentCondition object to identify messages based on whether a specific user's name appears in the From field.

• Add a PropVal object with properties set to the following values:
  • Set the IPropVal::Tag property to &H0C190102 (CdoPR_SENDER_ENTRY_ID).
  • Set the IPropVal::Value property to the ID property of the address entry. See the following code example for information on retrieving this property.
• Set the ICommentCondition::Condition property to a PropertyCondition object reference.
• Set the PropertyCondition object's properties to the following values:
  • Set the IPropertyCondition::Operator property to 7 (REL_EQ) to identify messages that are from this user or 5 (REL_NE) to identify messages that are not from this user.
  • Set the IPropertyCondition::PropertyTag property to &H0C1D0102 (CdoPR_SENDER_SEARCH_KEY).
  • Set the related PropVal object's properties to the following values:
  • Set the IPropVal::Tag property to &H0C1D0102 (CdoPR_SENDER_SEARCH_KEY).
  • Set the IPropVal::Value property to the search key of the address entry. See the following code example for information on retrieving this value.

Here's an example of a rule that deletes a message sent from the personal address book entry Spammer. It saves the sender's entry ID in a Comment condition, in case you later want to display further information about the sender in your script.

const CdoAddressListGAL        = 0             ' Global address list
const CdoAddressListPAB        = 1             ' Personal address book
const CdoPR_SENDER_ENTRYID     = &H0C190102

const CdoPR_SEARCH_KEY         = &H300B0102

const CdoPR_SENDER_SEARCH_KEY  = &H0C1D0102

const REL_EQ                   = 7
const ACTION_DELETE            = 3

' Create the rules object
Set objRules = CreateObject("MSExchange.Rules")

' Create the CDO MAPI session
Set objSession = CreateObject("MAPI.Session")

' Logon to \\SERVER as TestUser
objSession.Logon   "","",False,True,True,True,"SERVER" & vbLF & "TestUser"

' Get the Rules collection on TestUser's Inbox
objRules.Folder = objSession.Inbox

' Get Address Entries for Personal Address Book (PAB)
Set objPAB        = objSession.GetAddressList(CdoAddressListPAB)
Set objPABEntries = objPAB.AddressEntries

Found = False

' Search PAB entries for Spammer
For Each objFromAddress In objPABEntries
  If objFromAddress.Name = "Spammer" Then
    ' Get search key of the address entry
    SenderSearchKey = objFromAddress.Fields(CdoPR_SEARCH_KEY)
    Found = True
    Exit For
  End If
Next

If NOT Found Then
  Wscript.Echo "Address for Spammer not found!"
  Wscript.Quit
End If

' Create a rule for Inbox
Set objRule = CreateObject("MSExchange.Rule")
objRule.Name = "From Spammer Test"

' Get entry ID of address entry
Set objIDPropVal   = CreateObject("MSExchange.PropertyValue")
objIDPropVal.Tag   = CdoPR_SENDER_ENTRYID
objIDPropVal.Value = objFromAddress.ID

' Set Property Value with search key for Property Condition
Set objSearchPropVal   = CreateObject("MSExchange.PropertyValue")
objSearchPropVal.Tag   = CdoPR_SENDER_SEARCH_KEY
objSearchPropVal.Value = SenderSearchKey

' Set Property Condition
Set objPropCond         = CreateObject("MSExchange.PropertyCondition")
objPropCond.Operator    = REL_EQ
objPropCond.PropertyTag = CdoPR_SENDER_SEARCH_KEY
objPropCond.Value       = objSearchPropVal

' Set the comment condition
Set objCmtCond       = CreateObject("MSExchange.CommentCondition")
objCmtCond.Condition = objPropCond
objCmtCond.Add         objIDPropVal

' Set Action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE
objRule.Actions.Add    , objAction

' Assign Condition
objRule.Condition = objCmtCond

' Add the rule
objRules.Add ,objRule

' Commit the change
objRules.Update

' Logoff the MAPI session
objSession.Logoff

' Relese the objects we created
Set objRules          = Nothing
Set objSession        = Nothing
Set objPAB            = Nothing
Set objPABEntries     = Nothing
Set objFromAddress    = Nothing
Set objRule           = Nothing
Set objIDPropVal      = Nothing
Set objSearchPropVal  = Nothing
Set objPropCond       = Nothing
Set objCmtCond        = Nothing
Set objAction         = Nothing

Identifying Messages by Text in the Subject Field or Body of the Message

Use the ContentCondition object to identify messages based on text in the Subject field or body of the message.

1. Set the IContentCondition::Operator property to the appropriate value, such as &H00010001 (SUBSTRING + IGNORECASE) to allow sub-string and non-case-sensitive matches.
2. Set the IContentCondition::PropertyType property to &H1000001E (CdoPR_BODY) to search for the text in the body of the message, or &H0037001E (CdoPR_SUBJECT) to search for the text in the Subject field.
3. Set the related PropVal object's IPropVal::Tag property to the same CDO property as you did for the ContentCondition object's PropertyTag property.

Here's an example of a rule that deletes a message with the word delete in the Subject field.

const SUBSTRING      = 1
const IGNORECASE     = &H00010000

const ACTION_DELETE  =  3
const CdoPR_BODY     = &H1000001E

const CdoPR_SUBJECT  = &H0037001E


' Create PropVal
Set objPropVal   = CreateObject("MSExchange.PropertyValue")
objPropVal.Tag   = CdoPR_SUBJECT
objPropVal.Value = "delete"

' Create ContentCondition
Set objContCond          = CreateObject("MSExchange.ContentCondition")
objContCond.PropertyType = CdoPR_SUBJECT
objContCond.Operator     = SUBSTRING + IGNORECASE
objContCond.Value        = objPropVal

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create Rule object
Set objRule  = CreateObject("MSExchange.Rule")
objRule.Name = "Subject Test"

' Set condition and add action
objRule.Condition   = objContCond
objRule.Actions.Add   ,objAction

' Create session object and logon
Set objCDOSess     = CreateObject("MAPI.Session")
objCDOSess.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Create Rules object and add new Rule to Inbox collection
Set objRules      = CreateObject("MSExchange.Rules")
objRules.Folder  = objCDOSess.Inbox
objRules.Add       objRules.Count + 1, objRule

' Update the collection and cleanup
objRules.Update

objCDOSess.Logoff

Set objRules    = Nothing
Set objCDOSess  = Nothing
Set objRule     = Nothing
Set objContCond = Nothing
Set objPropVal  = Nothing
Set objAction   = Nothing

Identifying Messages by the Importance Level

Use the PropertyCondition object to identify messages based on its Importance.

1. Set the IPropertyCondition::Operator property an appropriate value, such as to 7 (REL_EQ) to identify messages of a specific importance level.
2. Set the IPropertyCondition::PropertyTag property to &H00170003 (CdoPR_IMPORTANCE).
3. Set the related PropVal object properties to the following values:
   1. Set the IPropVal::Tag property to &H00170003 (CdoPR_IMPORTANCE).
   2. Set the IPropVal::Value property to 0 (IMPORTANCE_LOW), 1 (IMPORTANCE_NORMAL), or 2 (IMPORTANCE_HIGH).

Here's an example of a rule that deletes messages of low importance.

const REL_EQ               = 7
const ACTION_DELETE        = 3
const CdoPR_IMPORTANCE     = &H00170003

const IMPORTANCE_LOW       = 0

' Create PropVal for messages with low importance
Set importPropVal      = CreateObject("MSExchange.PropertyValue")
importPropVal.Tag      = CdoPR_IMPORTANCE
importPropVal.Value    = IMPORTANCE_LOW

' Create property condition for when the importance is low
Set importPropCond         = CreateObject("MSExchange.PropertyCondition")
importPropCond.PropertyTag = CdoPR_IMPORTANCE
importPropCond.Operator    = REL_EQ
importPropCond.Value       = importPropVal

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create new rule
Set objRule   = CreateObject("MSExchange.Rule")
objRule.Name  = "Importance Test"

' Add action and assign condition
objRule.Actions.Add   , objAction
objRule.Condition   = importPropCond

' Open MAPI session and log on
Set objSession   = CreateObject("MAPI.Session")

' Log onto \\SERVER as TestUser
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Get Rules
Set objRules     = CreateObject("MSExchange.Rules")

' Open TestUser's inbox
objRules.Folder  = objSession.Inbox

' Add rule and update
objRules.Add  , objRule
objRules.Update

' Log off and cleanup
objSession.Logoff

Set objRules       = Nothing
Set objSession     = Nothing
Set importProp     = Nothing
Set importPropVal  = Nothing
Set objAction      = Nothing
Set objRule        = Nothing

Identifying Messages by the Sensitivity Level

Use the PropertyCondition object to identify messages based on its Sensitivity level.

1. Set the IPropertyCondition::Operator property an appropriate value, such as to 7 (REL_EQ) to identify messages of a specific sensitivity level.
2. Set the IPropertyCondition::PropertyTag property to &H00360003 (CdoPR_SENSITIVITY).
3. Set the related PropVal object properties to the following values:
   1. Set the IPropVal::Tag property to &&H00360003 (CdoPR_SENSITIVITY).
   2. Set the IPropVal::Value property to 0 (SENSITIVITY_NONE ), 1 (SENSITIVITY_PERSONAL), 2 (SENSITIVITY_PRIVATE), or 3 (SENSITIVITY_COMPANY_CONFIDENTIAL).

Here's an example of a rule that deletes messages marked company confidential.

const REL_EQ                            = 7
const ACTION_DELETE                     = 3
const CdoPR_SENSITIVITY                 = &H00360003

const SENSITIVITY_COMPANY_CONFIDENTIAL  = 3

' Create PropVal for messages marked company confidential
Set importPropVal      = CreateObject("MSExchange.PropertyValue")
importPropVal.Tag      = CdoPR_SENSITIVITY
importPropVal.Value    = SENSITIVITY_COMPANY_CONFIDENTIAL

' Create property condition for when the message is marked company confidential
Set importPropCond         = CreateObject("MSExchange.PropertyCondition")
importPropCond.PropertyTag = CdoPR_SENSITIVITY
importPropCond.Operator    = REL_EQ
importPropCond.Value       = importPropVal

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create new rule
Set objRule   = CreateObject("MSExchange.Rule")
objRule.Name  = "Sensitivity Test"

' Add action and assign condition
objRule.Actions.Add   , objAction
objRule.Condition   = importPropCond

' Open MAPI session and log on
Set objSession   = CreateObject("MAPI.Session")

' Log onto \\SERVER as TestUser
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Get Rules
Set objRules     = CreateObject("MSExchange.Rules")

' Open TestUser's inbox
objRules.Folder  = objSession.Inbox

' Add rule and update
objRules.Add  , objRule
objRules.Update

' Log off and cleanup
objSession.Logoff

Set objRules       = Nothing
Set objSession     = Nothing
Set importProp     = Nothing
Set importPropVal  = Nothing
Set objAction      = Nothing
Set objRule        = Nothing

Identifying Messages with Attachments

Use the BitmaskCondition object to identify messages with attachments.

1. Set the IBitmaskCondition::Operator property to either 1 (B_EQZ) for a bit-wise and equal to zero evaluation or 2 (B_NEZ) for a bit-wise and not equal to zero evaluation.
2. Set the IBitmaskCondition::PropertyTag property to &H0E070003 (CdoPR_MESSAGE_FLAGS).
3. Set the related PropVal object properties to the following values:
   1. Set the IPropVal::Tag property to &H0E070003 (CdoPR_MESSAGE_FLAGS).
   2. Set the IPropVal::Value property to &10 (MSGFLAG_HASATTACH).

Here's an example of a rule that deletes messages with attachments.

const ACTION_DELETE        = 3
const CdoPR_MESSAGE_FLAGS  = &H0E070003

const MSGFLAG_HASATTACH    = &H10

const B_NEZ                = 2

' Create property condition for when the message has attachments
Set BitMaskPropCond         = CreateObject("MSExchange.PropertyCondition")
BitMaskPropCond.PropertyTag = CdoPR_MESSAGE_FLAGS
BitMaskPropCond.Operator    = B_NEZ
BitMaskPropCond.Value       = MSGFLAG_HASATTACH

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create new rule
Set objRule   = CreateObject("MSExchange.Rule")
objRule.Name  = "Attachment Test"

' Add action and assign condition
objRule.Actions.Add   , objAction
objRule.Condition   = BitMaskPropCond

' Open MAPI session and log on
Set objSession   = CreateObject("MAPI.Session")

' Log onto \\SERVER as TestUser
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Get Rules
Set objRules     = CreateObject("MSExchange.Rules")

' Open TestUser's inbox
objRules.Folder  = objSession.Inbox

' Add rule and update
objRules.Add  , objRule
objRules.Update

' Log off and cleanup
objSession.Logoff

Set objRules       = Nothing
Set objSession     = Nothing
Set importProp     = Nothing
Set importPropVal  = Nothing
Set objAction      = Nothing
Set objRule        = Nothing

Identifying Messages by the Sent Time

Use the PropertyCondition object to identify messages based on when the message was sent.

1. Set the IPropertyCondition::Operator property an appropriate value, such as to 3 (REL_LE) to identify messages sent on or before a certain time.
2. Set the IPropertyCondition::PropertyTag property to &H30070040 (CdoPR_CREATION_TIME).
3. Set the related IPropertyCondition::Value object properties to the following values:
   1. Set the IPropertyCondition::PropertyTag property to &H30070040 (CdoPR_CREATION_TIME).
   2. Set the IPropertyCondition::Value property to the time. Use the TimeValue function to get the appropriate time.

Here's an example of a rule that deletes messages sent before midnight.

const REL_LE               = 3
const ACTION_DELETE        = 3
const CdoPR_CREATION_TIME  = &H30070040


Midnight = CDate("9/14/98 0:00:00")

' Create PropVal for messages sent before midnight
Set CreatePropVal      = CreateObject("MSExchange.PropertyValue")
CreatePropVal.Tag      = CdoPR_CREATION_TIME
CreatePropVal.Value    = Midnight

' Create property condition for when the message was sent before midnight
Set CreatePropCond         = CreateObject("MSExchange.PropertyCondition")
CreatePropCond.PropertyTag = CdoPR_CREATION_TIME
CreatePropCond.Operator    = REL_LE
CreatePropCond.Value       = CreatePropVal

' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create new rule
Set objRule   = CreateObject("MSExchange.Rule")
objRule.Name  = "Sensitivity Test"

' Add action and assign condition
objRule.Actions.Add   , objAction
objRule.Condition   = CreatePropCond

' Open MAPI session and log on
Set objSession   = CreateObject("MAPI.Session")

' Log onto \\SERVER as TestUser
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Get Rules
Set objRules     = CreateObject("MSExchange.Rules")

' Open TestUser's inbox
objRules.Folder  = objSession.Inbox

' Add rule and update
objRules.Add  , objRule
objRules.Update

' Log off and cleanup
objSession.Logoff

Set objRules       = Nothing
Set objSession     = Nothing
Set importProp     = Nothing
Set importPropVal  = Nothing
Set objAction      = Nothing
Set objRule        = Nothing

Identifying Messages by Size

Use the SizeCondition object to identify messages based on the size of a property.

1. Set the ISizeCondition::Operator property to the appropriate relational operator, such as 2 (REL_GT) to identify a property whose size is greater than the given value.
2. Set the ISizeCondition::PropertyTag property to the property whose size you are comparing.
3. Set the ISizeCondition::Size property to the size to compare to the message property size.

Here's an example of a rule that deletes messages whose Body property is greater than 1Mbyte.

const REL_GT        = 2
const ACTION_DELETE = 3
const CdoPR_BODY    = &H1000001E


' Create property condition for when the message property is greater than SIZE
Set SizeProp         = CreateObject("MSExchange.SizeCondition")
SizeProp.PropertyTag = CdoPR_BODY
SizeProp.Operator    = REL_GT
SizeProp.Size        = &H100000


' Create action
Set objAction        = CreateObject("MSExchange.Action")
objAction.ActionType = ACTION_DELETE

' Create new rule
Set objRule   = CreateObject("MSExchange.Rule")
objRule.Name  = "Size Test"

' Add action and assign condition
objRule.Actions.Add   , objAction
objRule.Condition   = SizeProp

' Open MAPI session and log on
Set objSession   = CreateObject("MAPI.Session")

' Log onto \\SERVER as TestUser
objSession.Logon "","",false,true,true,true,"SERVER" & vbLF & "TestUser"

' Get Rules
Set objRules     = CreateObject("MSExchange.Rules")

' Open TestUser's inbox
objRules.Folder  = objSession.Inbox

' Add rule and update
objRules.Add  , objRule
objRules.Update

' Log off and cleanup
objSession.Logoff

Set objRules       = Nothing
Set objSession     = Nothing
Set importProp     = Nothing
Set importPropVal  = Nothing
Set objAction      = Nothing
Set objRule        = Nothing

Creating Conditions

The major effort in creating a rule is building a condition. It's trivial to create simple (one condition object) conditions. For example, to trap messages that are greater than 50Kbytes in size, use SizeCondition. It's when you need to create a condition with multiple condition objects that things get interesting.

To save yourself a lot of grief, try first drawing a logic tree. For example, to specify a condition where mail sent to you, from MyLittleBrother, and marked low importance, you might create the following diagram:

You typically build a condition object from the bottom up. In this example:

1. Create the property condition for when importance is low.
2. Create the property condition when the message is sent directly to you.
3. Create the property condition when the sender is MyLittleBrother.
4. Create the logical (and) condition for the latter two conditions.
5. Create the final logical (and) condition.

You can see the code that implements this condition in the Rule class example.

Creating a Content Condition

To create a ContentCondition, perform the following steps:

1. Create a PropVal object to hold the value of the string with which the Subject or Body field is compared.
   1. Set the IPropVal::Tag property to the CDO property CdoPR_BODY or CdoPR_SUBJECT.
   2. Set IPropVal::Value property to the string with which the Body or Subject field is compared.
2. Create a ContentCondition object.
   1. Set the IContentCondition::Value property to the new PropVal object.
   2. Set the IContentCondition::PropertyType property to the same CDO property value as the PropVal object's Tag property (CdoPR_BODY or CdoPR_SUBJECT).
   3. Set the IContentCondition::Operator property to the appropriate string operator, such as SUBSTRING to identify messages where the value matches any part of the Subject or Body field.

For example, to identify messages where the Subject field contains the string "Test":

const SUBSTRING         = 1

Set myPropVal   = CreateObject("MSExchange.PropVal")
myPropVal.Tag   = CdoPR_SUBJECT
myPropVal.Value = "Test"

Set myPropCond          = CreateObject("MSExchange.PropertyCondition")
myPropCond.Value        = myPropVal
myPropCond.PropertyType = CdoPR_SUBJECT
myPropCond.Operator     = SUBSTRING

Creating a Property Condition

To create a Property condition, perform the following steps:

1. Create a PropVal object.
   1. Set the IPropVal::Tag property to the CDO property value, such as CdoPR_MESSAGE_TO_ME to identify messages sent directly to you.
   2. Set the IPropVal::Value property to an appropriate value, such as True for CDO properties with property type PT_BOOLEAN.
1. Create a PropertyCondition object.
   1. Set the IPropertyCondition::Value property to the new PropVal object.
   2. Set the IPropertyCondition::PropertyTag property to the same CDO property as the PropVal objects's Tag property.
   3. Set the IPropertyCondition::Operator property to the appropriate relational operator, such as REL_EQ for properties that equal the given value.

For example, to identify messages sent to you:

const CdoPR_MESSAGE_TO_ME = &H0057000B

const REL_EQ = 7

Set myPropVal   = CreateObject("MSExchange.PropVal")
myPropVal.Tag   = CdoPR_MESSAGE_TO_ME
myPropVal.Value = TRUE

Set myPropCond         = CreateObject("MSExchange.PropertyCondition")
myPropCond.Operator    = REL_EQ
myPropCond.PropertyTag = CdoPR_MESSAGE_TO_ME
myPropCond.Value       = myPropVal
  

Creating a CompareProps Condition

To create a ComparePropsCondition, perform the following steps:

1. Create a ComparePropsCondition object.
2. Set the IComparePropsCondition::PropertyTag1 property to the first property you are comparing.
2. Set the IComparePropsCondition::PropertyTag2 property to the other property you are comparing.
3. Set the IComparePropsCondition::Operator property to the relational operator you are using to compare, such as 4 (REL_LT), which makes the condition True when PropertyTag1 is less than PropertyTag2.

For example, to identify messages where the sensitivity level is higher than what the original sender specified:

const CdoPR_ORIGINAL_SENSITIVITY = &H002E0003

const CdoPR_SENSITIVITY          = &H00360003

const REL_LT = 4

Set myCmpPropCond          = CreateObject("MSExchange.ComparePropsCondition")
myCmpPropCond.Operator     = REL_LT
myCmpPropCond.PropertyTag1 = CdoPR_ORIGINAL_SENSITIVITY
myCmpPropCond.PropertyTag2 = CdoPR_SENSITIVITY

Creating a BitmaskCondition

To create a BitmaskCondition, perform the following steps:

1. Create a BitmaskCondition object.
2. Set the IBitmaskCondition::Value property to the value to mask the property.
3. Set the IBitmaskCondition::PropertyTag property to the CDO property to compare with the bitmask value.
4. Set the IBitmaskCondition::Operator property to either 1 (B_EQZ) to make a bit-wise AND equal to zero comparison or 2 (B_NEZ) to make a bit-mask AND not equal to zero comparison.

For example, to identify messages with attachments:

const CdoPR_MESSAGE_FLAGS  = &H0E070003

const MSGFLAG_HASATTACH    = &H10

const B_NEZ                = 2

Set myPropVal      = CreateObject("MSExchange.PropertyValue")
myPropVal.Tag      = CdoPR_MESSAGE_FLAGS
myPropVal.Value    = MSGFLAG_HASATTACH

Set BitMaskPropCond         = CreateObject("MSExchange.PropertyCondition")
BitMaskPropCond.PropertyTag = CdoPR_MESSAGE_FLAGS
BitMaskPropCond.Operator    = B_NEZ
BitMaskPropCond.Value       = myPropVal
  

Creating a SizeCondition

To create a SizeCondition, perform the following steps:

1. Create a SizeCondition object.
2. Set the ISizeCondition::Operator property to the relational operator, such as 2 (REL_GT) to identify message property sizes greater than the given size.
3. Set the ISizeCondition::PropertyTag property to the property whose size you are comparing.
4. Set the ISizeCondition::Size property to the size to compare to the message property size.

For example, to identify messages whose body size is greater than 1 MBtye:

const REL_GT               = 2
const CdoPR_BODY           = &H1000001E

const SIZE                 = &H100000


Set SizeCond         = CreateObject("MSExchange.SizeCondition")
SizeCond.PropertyTag = CdoPR_BODY
SizeCond.Operator    = REL_GT
SizeCond.Size        = SIZE

Creating a SubCondition

To create a SubCondition, perform the following steps:

1. Create a Condition object for the subordinate condition.
2. Create the SubCondition object.
   1. Set the ISubCondition::Condition property to the new Condition object.
   2. Set the ISubCondition::Operator property to either 1 (MSG_RECIP) to create a message recipient sub condition or 2 (MSG_ATTCH) to create a message attachment sub condition.

For example, to identify messages with attachments named junk.gif:

const CdoPR_ATTACH_FILENAME = &H3704001E

const REL_EQ                = 7
const MSG_ATTACH            = 2

Set objPropVal   = CreateObject("MSExchange.PropertyValue")
objPropVal.Tag   = CdoPR_ATTACH_FILENAME
objPropVal.Value = "junk.gif"

Set objPropCond         = CreateObject("MSExchange.PropertyCondition")
objPropCond.Value       = objPropVal
objPropCond.Operator    = REL_EQ
objPropCond.PropertyTag = CdoPR_ATTACH_FILENAME

Set objSubCond       = CreateObject("MSExchange.SubCondition")
objSubCond.Condition = objPropCond
objSubCond.Operator  = MSG_ATTACH
...
  

Creating an ExistsCondition

To create an ExistsCondition, perform the following steps:

1. Create an ExistsCondition object.
2. Set the IExistsCondition::PropertyTag property to the property you want to check for existence. Essentially this condition is always satisfied.

For example, to identify messages where the CdoPR_ACCOUNT property (&H3A00001E) is set:

const CdoPR_ACCOUNT = &H3A00001E


Set objExistsCond         = CreateObject("MSExchange.ExistsCondition")
objExistsCond.PropertyTag = CdoPR_ACCOUNT
...
  

Creating a LogicalCondition

To create a LogicalCondition, perform the following steps:

1. Create a Condition object.
2. If necessary, create a second Condition object.
3. Create the LogicalCondition object.
   1. Set the ILogicalCondition::Operator property to the desired logical operation, such as 1 (L_AND) for logical AND.
   2. Call the ILogicalCondition::Add method once to add the first condition for a unary NOT operation, twice to add both conditions for a binary AND or OR operation.

For example, to identify messages marked as low importance from Fred:

const CdoPR_SENDER_NAME = &H0C1A001E

const REL_EQ            = 7
const CdoPR_IMPORTANCE  = &H00170003

const IMPORTANCE_LOW    = 0
const L_AND             = 1

Set fromPropVal   = CreateObject("MSExchange.PropertyValue")
fromPropVal.Tag   = CdoPR_SENDER_NAME
fromPropVal.Value = "Fred"

Set fromPropCond         = CreateObject("MSExchange.PropertyCondition")
fromPropCond.Value       = fromPropVal
fromPropCond.Operator    = REL_EQ
fromPropCond.PropertyTag = CdoPR_SENDER_NAME

Set importPropVal   = CreateObject("MSExchange.PropertyValue")
importPropVal.Tag   = CdoPR_IMPORTANCE
importPropVal.Value = IMPORTANCE_LOW

Set importPropCond         = CreateObject("MSExchange.PropertyCondition")
importPropCond.PropertyTag = CdoPR_IMPORTANCE
importPropCond.Operator    = REL_EQ
importPropCond.Value       = importPropVal

Set logPropCond      = CreateObject("MSExchange.LogicalCondition")
logCond.Operator = L_AND
logCond.Add        , importPropCond
logCond.Add        , fromPropCond
...
  

Finishing Up

Once you've created your actions and condition, add the actions to your new rule using the Rule.Actions.Add method, and assign the condition to the rule by setting the IRule::Condition property to the condition object. Don't forget to call the Rules collection's IRules::Update method to make your changes permanent.