Click or drag to resize

Conditions and exceptions

CodeTwo Exchange Rules Pro processes messages according to defined conditions. Conditions and exceptions are sets of filters enumerated while qualifying the rules to be processed or not. These filters, depending if you use them as conditions or exceptions, are added to an adequate collection of conditions or exceptions. Individual filters within a collection are bound with logical relationships that can be configured. By default, the And logical operator is used (it's implicit):

C#
//Add a first filter to conditions' collection
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Recipient));

//Add a second filter to conditions' collection
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Sender));

To define the Or operator, you should separate filters within the collection with FilterOr:

C#
//Add a first filter to conditions' collection
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Recipient));

//Add the Or operator
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterOr());

//Add a second filter to conditions' collection
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Sender));

The example below shows how to create a new rule via a custom application. This rule contains a Block message action which is triggered if the recipient's email address matches a defined email address. Finally, the rule is uploaded to the Settings Storage WCF Service using UploadChanges(String, ItemsSnapshotTRuleDesc):

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Sample rule";

//Activate the rule
rule.Active = true;

//Create a Block message action and add it to the created rule
var actionBlockMessage = new Settings.Actions.ActionBlockMessage();
rule.Actions.Add(actionBlockMessage);

//Check if the recipient's email address matches blockeduser@domain.com
var filterSmtpAddress = new ER.Shared.Settings.Filters.FilterUserSmtpAddress();
filterSmtpAddress.Addresses = new string[] { "blockeduser@domain.com" };
filterSmtpAddress.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;
rule.Conditions.Add(filterSmtpAddress);

//Create a snapshot and add the rule to this snapshot
var snapshot = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshot.NewItems = new Settings.RuleDesc[] { rule };
snapshot.AllItemsIds = snapshot.NewItems.Select(r => r.ID).ToArray();

//Upload the snapshot to SettingsStorage
var client = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
client.UploadChanges(null, snapshot);

Learn more about the recommended way of uploading new/modified/deleted rules from a custom app to the Settings Storage WCF Service

This article consists of the following sections:

Conditions

Conditions define if a given rule will be processed. If the logical expression based on filters is set to true then the rule will be triggered.

C#
//This rule will be executed when a recipient or sender is internal
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Recipient));
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserInternal(ER.Shared.Settings.Filters.EnumPersonType.Sender));

The table below presents all conditions available via the provided API, with their description and code entity reference:

Condition's name

Description

Available operators

Code entity reference

Additional info

Sender

Used within a rule to define the scope of senders that, once met, will trigger the program to process the rule and perform associated action(s).

  • Has a specific email address

  • Matches AD user

  • Belongs to AD group

  • Matches AD filter

  • Matches AD group

  • Belongs to OU

  • Is internal

  • Is external

  • Is disabled in AD

A full list of filter classes can be found within ER.Shared.Settings.Filters

Recipient

Used within a rule to define the scope of recipients that, once met, will trigger the program to process the rule and perform associated action(s).

  • Has a specific email address

  • Matches AD user

  • Belongs to AD group

  • Matches AD filter

  • Matches AD group

  • Belongs to OU

  • Is internal

  • Is external

  • Is disabled in AD

A full list of filter classes can be found within ER.Shared.Settings.Filters.

The current API version does not allow you to create a condition/exception in which a recipient belongs to a blacklist.

Subject

Used within a rule to define phrases within the message subject that, once met, will trigger the program to process the rule and perform associated action(s).

  • Matches exact phrase

  • Matches regular expression

  • Contains keyword(s)

Currently the provided API excludes the possibility to make rules created in the app search for sensitive content within the subject of a message.

Body

Used within a rule to define phrases within the message body (the content of an email) that, once met, will trigger the program to process the rule and perform associated action(s).

  • Contains keyword(s)

Currently the provided API excludes the possibility to make rules created in the app search for sensitive content within the body of a message.

Message direction

Used within a rule to specify the message direction type that, once met, will trigger the program to process the rule and perform associated action(s).

  • Is internal

  • Is outgoing

  • Is incoming

The value of the chosen operator needs to be defined using EnumMessageDirection, e.g.

C#
filterMessageDirection.Value = Settings.Filters.EnumMessageDirection.Internal;

Message type

Used within a rule to specify the message type that, once met, will trigger the program to process the rule and perform associated action(s).

  • Is new email

  • Is reply or forward

  • Is out of office

  • Is meeting request

The value of the chosen operator needs to be defined using EnumMessageType, e.g.

C#
filterMessageType.MessageType = Common.EnumMessageType.typeOutOfOffice;

Attachments

Used within a rule to specify the number/size/extension of attachments that, once met, will trigger the program to process the rule and perform associated action(s).

  • There are none / is at least one / specific number of attachments

  • At least one of the attachments has specified extension

  • The individual attachment is between the specified size range

  • A cumulative size of all attachments is within the specified size range

Depending on the AttachmentFilterType the value of condition can be configured using the following properties:

Code examples of conditions

The table below shows code examples of each condition available via the provided API, along with a corresponding entity reference.

Condition's name

Code example

Sender / Recipient

Checking if the sender's main email address (including aliases) matches a defined SMTP address (an exact email address or the one containing wildcards defined by asterisks).

Code entity reference: FilterUserSmtpAddress

C#
//Create a Sender condition
var filterUserSmtpAddress = new ER.Shared.Settings.Filters.FilterUserSmtpAddress();

//Check if the sender’s email address matches manager@domain.com or sales*@domain.com.
//Asterisk substitutes any sequence of characters in the address.
filterUserSmtpAddress.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Sender;
filterUserSmtpAddress.Addresses = new string[] { "manager@domain.com", "sales*@domain.com" };

//Also check email aliases
filterUserSmtpAddress.UseMainAddressOnly = false;

Checking if the recipient's email address equals a defined Active Directory user's address.

Code entity reference: FilterUserIsAdUser

C#
//Check if the recipient matches a defined AD user
var filterUserIsAdUser = new ER.Shared.Settings.Filters.FilterUserIsAdUser();
filterUserIsAdUser.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;
filterUserIsAdUser.DistinguishedName = new C2Common.AD.CDistinguishedName("CN=Patryk,OU=Users,OU=Developers,DC=company,DC=local");

Checking if the sender's email address applies to a user who belongs to a chosen group in Active Directory.

Code entity reference: FilterUserIsMemberOfGroup

C#
//Check if the email sender is a member of a defined AD group
var filterUserIsMemberOfGroup = new ER.Shared.Settings.Filters.FilterUserIsMemberOfGroup();
filterUserIsMemberOfGroup.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Sender;
filterUserIsMemberOfGroup.DistinguishedName = new C2Common.AD.CDistinguishedName("CN=Developers,DC=company,DC=local");

Checking if the recipient has an Extension Attribute filled in Active Directory that equals a chosen value.

Code entity reference: FilterUserAdProperty

C#
//Create a Recipient condition
var filterUserProperty = new ER.Shared.Settings.Filters.FilterUserAdProperty();

//Check the recipient of a message
filterUserProperty.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;

//Check if the recipient’s extensionAttribute15 value equals "CompanyB"
filterUserProperty.Criterion = new C2Common.AD.ADPropertyCompareCriterion();
filterUserProperty.Criterion.PropertyName = new C2Common.AD.ADPropertyName(C2Common.AD.EnumLdapPropertyNames.extensionAttribute15);
filterUserProperty.Criterion.PropertyValue = new C2Common.AD.ADValueString("CompanyB");
filterUserProperty.Criterion.ComparsionType = C2Common.AD.EnumComparsionType.typeEquals;

Checking if the recipient belongs to a chosen Organizational Unit in Active Directory.

Code entity reference: FilterUserOrganizationalUnit

C#
//Check if the recipient belongs to a defined OU
var filterOrganizationalUnit = new ER.Shared.Settings.Filters.FilterUserOrganizationalUnit();
filterOrganizationalUnit.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;
filterOrganizationalUnit.DistinguishedName = new C2Common.AD.CDistinguishedName("OU=Developers,DC=company,DC=local");

Checking if the recipient is an internal user (this user can be found in your Active Directory).

Code entity reference: FilterUserInternal

C#
//Create a Recipient condition
var filterUserInternal = new ER.Shared.Settings.Filters.FilterUserInternal();

//Check if the email recipient is internal
filterUserInternal.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;

Checking if the sender is an external user (this user cannot be found in your Active Directory).

Code entity reference: FilterUserExternal

C#
//Create a Sender condition
var filterUserExternal = new ER.Shared.Settings.Filters.FilterUserExternal();

//Check if the email sender is external
filterUserExternal.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Sender;

Checking if the recipient is a user whose account is disabled in Active Directory.

Code entity reference: FilterUserDisabled

C#
//Create a Recipient condition
var filterUserDisabled = new ER.Shared.Settings.Filters.FilterUserDisabled();

//Check if the email recipient is disabled in AD
filterUserDisabled.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;

Subject / Body

Examining the subject and body of a message in search of phrases containing defined keywords.

Code entity reference: FilterFindKeyword

C#
//Create a Body and Subject condition
var filterFindKeyword = new Settings.Filters.FilterFindKeyword();

//Search for keywords in the message subject & body
filterFindKeyword.Location = Settings.Phrases.EnumTextSearchLocation.locationSubject | Settings.Phrases.EnumTextSearchLocation.locationBody;

//Search for the ‘NoSig’ keyword and remove it if found
filterFindKeyword.Keywords = new Settings.Filters.FilterFindKeyword.Keyword[] {
    new Settings.Filters.FilterFindKeyword.Keyword("NoSig", true)
};

Looking through the subject of a message in search of exact phrases.

Code entity reference: FilterSubjectEquals

C#
//Create a Subject condition
var filterSubjectEquals = new Settings.Filters.FilterSubjectEquals();
filterSubjectEquals.Phrase = "Sample message subject";

Looking through the subject of a message in search of a regular expression.

Code entity reference: FilterSubjectRegex

C#
//Create a Subject condition
var filterSubjectRegex = new Settings.Filters.FilterSubjectRegex();

//Search for a price pattern
filterSubjectRegex.Pattern = @"\d+[\.,]\d{2}";

Message direction

Checking if a message is sent inside an organization.

Code entity reference: FilterMessageDirection

C#
//Create a Message direction condition
var filterMessageDirection = new Settings.Filters.FilterMessageDirection();
filterMessageDirection.Value = Settings.Filters.EnumMessageDirection.Internal;

Message type

Analyzing if the message is of the Out of Office type.

Code entity reference: FilterMessageType

C#
//Create a Message type condition
var filterMessageType = new Settings.Filters.FilterMessageType();
filterMessageType.MessageType = Common.EnumMessageType.typeOutOfOffice;

Attachments

Defining a filter to search for the size range (minimum and maximum size) of individual attachments included in messages.

Code entity reference: FilterAttachments

C#
//Create an Attachments condition
var filterAttachments = new Settings.Filters.FilterAttachments();

//Filter attachments by size
filterAttachments.AtachmentFilterType = Settings.Filters.FilterAttachments.EnumAttachmentFilter.ByFileSize;
filterAttachments.SizeDesc = new Settings.Filters.Attachments.AttachmentsSizeDesc();

//Check the total size of attachments
filterAttachments.SizeDesc.WhatToCheck = Settings.Filters.Attachments.AttachmentsSizeDesc.EnumWhatToCheck.TotalSize;

//Filter only attachments with a minimum size of 100 kB and a maximum size of 2 MB
filterAttachments.SizeDesc.From = new Settings.Filters.Attachments.AttachmentsSizeDesc.SizeDesc(100 /* kB */);
filterAttachments.SizeDesc.To = new Settings.Filters.Attachments.AttachmentsSizeDesc.SizeDesc(2 * 1024 /* MB */);

Grouping of conditions

Besides adding individual conditions to rules, you can also group selected conditions in any way you want using FilterCollection. Thanks to this solution, any clause of grouped conditions can work as a separate unit from the other conditions defined within the same rule.

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Sample name";

//Activate the rule
rule.Active = true;

//Create a Block message action
rule.Actions.Add(new Settings.Actions.ActionBlockMessage());

//Create filters and group them.
var group = new ER.Shared.Settings.Filters.FilterCollection();
group.Add(new ER.Shared.Settings.Filters.FilterUserInternal());
group.Add(new ER.Shared.Settings.Filters.FilterOr());
group.Add(new ER.Shared.Settings.Filters.FilterUserDisabled());

//Add the group of filters to conditions
rule.Conditions.Add(group);

//Add another filter to conditions (it will be added separately from the group of filters)
rule.Conditions.Add(new ER.Shared.Settings.Filters.FilterUserExternal());

//Create a snapshot for adding the rule
var snapshotCreate = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshotCreate.NewItems = new Settings.RuleDesc[] { rule };
snapshotCreate.AllItemsIds = snapshotCreate.NewItems.Select(r => r.ID).ToArray();

//Upload the snapshot to SettingsStorage
var client = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
client.UploadChanges(null, snapshotCreate);
Exceptions

Exceptions exclude rules from processing. It means that if a logical expression based on filters is set to true then the rule won't be triggered. Exceptions are configured in the same way as conditions, including the grouping options. To define exceptions you need to add filters to the Exceptions collection.

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.ID = Guid.NewGuid().ToString();
rule.Name = "Sample rule";

//Activate the rule
rule.Active = true;

//Create a Block message action and add it to the created rule
var actionBlockMessage = new Settings.Actions.ActionBlockMessage();
rule.Actions.Add(actionBlockMessage);

//Check if the recipient's email address matches *@domain.com
var filterSmtpAddress = new ER.Shared.Settings.Filters.FilterUserSmtpAddress();
filterSmtpAddress.Addresses = new string[] { "*@domain.com" };
filterSmtpAddress.PersonType = ER.Shared.Settings.Filters.EnumPersonType.Recipient;
rule.Conditions.Add(filterSmtpAddress);

//The rule will not be executed when the recipient is joe@domain.com
rule.Exceptions.Add(
  new ER.Shared.Settings.Filters.FilterUserSmtpAddress("joe@domain.com", false, ER.Shared.Settings.Filters.EnumPersonType.Recipient));

//Create a snapshot and add the rule to this snapshot
var snapshot = new Settings.ItemsSnapshotT<Settings.RuleDesc>();
snapshot.NewItems = new Settings.RuleDesc[] { rule };
snapshot.AllItemsIds = snapshot.NewItems.Select(r => r.ID).ToArray();

//Upload the snapshot to SettingsStorage
var client = new ER.SDK.SettingsStorageClient("SettingsStorageHttpEndpoint");
client.UploadChanges(null, snapshot);
See also

Configuration of tenants - how to implement the tenant configuration capability in a custom app via the provided API.