Click or drag to resize

Actions

Actions in CodeTwo Exchange Rules Pro represent activities that are performed on messages processed by a given rule. The execution of actions depends on conditions / exceptions that, once met, will initiate/suppress the associated actions.

The example below shows how to create a new rule with a Block message action via a custom application and upload it to the Settings Storage WCF Service using using UploadChanges(String, ItemsSnapshotTRuleDesc):

C#
//Create a new rule
var rule = new Settings.RuleDesc();
rule.Active = true;
rule.Name = "Sample rule";

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

//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:

Actions provided via API

To implement actions in a rule, you need to add them to the collection of Actions. Therefore, the order in which actions will be executed for a particular rule will depend on the order in which these actions were added to the collection. In the example below, the Block message action will be triggered first.

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;

//Add a first action to the collection of actions
rule.Actions.Add(new Settings.Actions.ActionBlockMessage());

//Add a second action to the collection of actions
rule.Actions.Add(new Settings.Actions.ActionRemoveStationery());

The table below shows the list of all actions available via the provided API, with a description and code entity reference:

Action's name

Description

Support for placeholders

Code entity reference

Add attachment

Used to automatically add attachments to messages either from a hot folder collection or individual files.

The code example below shows how to create an Add attachment action that inserts attachments from a defined hot folder:

C#
//Create an Add attachments action
var actionAddAttachment = new Settings.Actions.ActionAddAttachment();
actionAddAttachment.FilesSource = Settings.EnumAttachmentFilesSource.sourceHotFolder;

//Insert attachments from a hot folder
actionAddAttachment.HotFolderPath = @"\\FileServer\Data\Attachments";

No

Add recipients

Used to automatically add additional recipients for messages.

The code example below shows how to create an Add recipients action that inserts a specified recipient in the Cc field:

C#
//Create an Add recipients action
var actionAddRecipients = new Settings.Actions.ActionAddRecipients();

//Insert an additional recipient in the Cc field
actionAddRecipients.Recipients.Add(
    new Settings.Actions.RecipientDesc("Administrator", "administrator@domain.com", Common.EnumRecipientType.typeCc));

No

Auto respond

Used to automatically send auto-respond (autoreply) messages.

The code example below shows how to create an Auto respond action. The format of the autoreply message template is set to HTML and the original message is included as an attachment.

C#
//Create an Auto respond action
var actionAutoRespond = new Settings.Actions.ActionAutoRespond();

//Set the auto-respond message format to HTML
actionAutoRespond.Format = Common.EnumMailFormat.formatHtml;

//Insert the original message to the auto-respond message
actionAutoRespond.OriginalMessageAction = Common.EnumOriginalMessageAction.InsertAsReply;

//Compose the auto-respond message template
actionAutoRespond.TemplateHtml.Content = "Sample autorespond message";

Yes

Apply full composition

Used to configure a ‘full’ template of signatures/disclaimers, i.e. a template containing all available layout elements: a header, a signature/disclaimer and side banners.

The code example below shows how to create an Apply full composition action with top (header) and bottom (signature/disclaimer) sections defined in the Plain Text format:

C#
//Create an Apply full composition action
var actionApplyFullComposition = new Settings.Actions.ActionApplyFullComposition();

//Within the Apply full composition action, set the composition’s layout to Plain Text
var compositionPureText = actionApplyFullComposition.CompositionLayout.PureText;

//Compose the content of the top (header) section
compositionPureText.Top.Content = "Sample top content";

//Compose the bottom (signature/disclaimer) section, including an {E-mail} placeholder in the template composition
compositionPureText.Bottom.Content = "Sample bottom content {E-mail}";

Yes

Block message

Used to stop messages from being sent or received.

The code example below shows how to create a Block message action that prevents emails from being sent/received (depending on defined conditions/exceptions):

C#
//Create a Block message action
var actionBlockMessage = new Settings.Actions.ActionBlockMessage();

No

Compress attachments

Used for automatic compression of email attachments.

The code example below shows how to create a Compress attachments action that compresses individual message attachments which are bigger than 1 MB, excluding some specific file formats:

C#
//Create a Compress attachments action
var actionCompressAttachments = new Settings.Actions.ActionCompressAttachments();
actionCompressAttachments.CompressionTreshold = 1 * 1024 * 1024; //1MB

//Do not compress *.jpg and *.bmp files
actionCompressAttachments.Exceptions = new string[] { "jpg", "bmp" };

No

Force email format

Used to automatically change the format of original messages to: Plain Text or HTML. Note that RTF is not supported.

The code example below shows how to create a Force email format action that converts the format of emails to HTML:

C#
//Create a Force e-mail format action
var actionForceEmailFormat = new ER.Shared.Settings.Actions.ActionForceEmailFormat();

//Convert messages to the HTML format
actionForceEmailFormat.TargetFormat = Common.EnumMailFormat.formatHtml;

No

Forward message

Used to automatically forward original messages to chosen users.

The code example below shows how to create a Forward message action that forwards an email to a defined address and replaces the original email subject with a text plus a selected placeholder

C#
//Create a Forward message action
var actionForwardMessage = new Settings.Actions.ActionForwardMessage2();

//Forward a message to administrator@domain.com
actionForwardMessage.Addresses.Add(new Settings.Actions.CAddressForwardMessage("administrator@domain.com"));

//The content of the {Original Subject} placeholder will be replaced with the subject of the original message 
actionForwardMessage.SubjectTemplate.Content = "Forwarded message: {Original Subject}";

Yes

  • ActionForwardMessage3

Insert disclaimer

Used to configure and automatically insert disclaimers into messages.

The code example below shows how to create an Insert disclaimer action that inserts a disclaimer in the Plain Text format. This disclaimer will contain a text and a chosen placeholder:

C#
//Create an Insert disclaimer action
var actionInsertDisclaimer = new Settings.Actions.ActionApplyInsertDisclaimer();

//Within the Insert disclaimer action, set the composition’s layout to Plain Text
var compositionPureText = actionInsertDisclaimer.CompositionLayout.PureText;

//Compose the bottom (disclaimer) section, including an {E-mail} placeholder in the template composition
compositionPureText.Bottom.Content = "Sample disclaimer for {E-mail}";

Yes

Insert signature

Used to configure and automatically insert signatures into messages.

The code example below shows how to create an Insert signature action that inserts a signature in the Plain Text format. This signature will contain a text and a chosen placeholder:

C#
//Create an Insert signature action
var actionInsertSignature = new Settings.Actions.ActionApplyInsertSignature();

// Within the Insert signature action, set the composition’s layout to Plain Text
var compositionPureText = actionInsertSignature.CompositionLayout.PureText;

//Compose the bottom (disclaimer) section, including an {E-mail} placeholder in the template composition
compositionPureText.Bottom.Content = "Sample signature for {E-mail}";

Yes

Modify subject

Used to automatically modify the subject of messages.

The code example below shows how to create a Modify subject action that replaces the subject of an email with a defined phrase:

C#
//Create a Modify subject action
var actionModifySubject = new Settings.Actions.ActionModifySubject();

//Modify the subject of a message
actionModifySubject.Template.Content = "Modified subject";

Yes

Remove keywords

Used to automatically remove defined keywords from messages.

The code example below shows how to create a Remove keywords action that removes a defined keyword from the subject and body of an email and removes the resulting white spaces:

C#
//Create a Remove keywords action and set your keyword phrase
var actionRemoveKeyword = new Settings.Actions.ActionRemoveKeyword();
var keywordNoSig = new Settings.Phrases.KeywordDesc("NoSig");

//The keyword will be removed from the message body and subject
keywordNoSig.SearchLocation = Settings.Phrases.EnumTextSearchLocation.locationBody | Settings.Phrases.EnumTextSearchLocation.locationSubject;
actionRemoveKeyword.Keywords.Add(keywordNoSig);

No

  • ActionRemoveKeyword2

Remove themes and stationery

Used to automatically remove all stationery from a message.

The code example below shows how to create a Remove themes and stationery action that removes all themes and stationery from an email:

C#
//Create a Remove themes and stationery action
var actionRemoveStationery = new Settings.Actions.ActionRemoveStationery();

No

Rewrite sender’s address

Used to automatically change the sender (the From field) of a message so that this message looks as if it arrived from another (user-specified) address.

The code example below shows how to create a Rewrite sender’s address action that replaces the original email sender's address with a defined email address. Additionally, the result of this action will depend on the sender's email address:

C#
//Create a Rewrite sender's address action
var actionSenderAddressRewrite = new Settings.Actions.ActionSenderAddressRewrite2();

//Rewrite the sender address to sales@domain.com if the original sender was administrator@domain.com
actionSenderAddressRewrite.Addresses.Add("administrator@domain.com", 
    new Settings.Actions.RewriteMapped("sales@domain.com", Settings.Actions.EnumDisplayNameChange.empty, null));

//Rewrite the sender address to other@domain.com for other senders
actionSenderAddressRewrite.UseDefaultAddress = true;
actionSenderAddressRewrite.DefaultRewrite = new Settings.Actions.RewriteMapped("other@domain.com", Settings.Actions.EnumDisplayNameChange.empty, null);

No

Note Note

This refers only to the Insert disclaimer/signature and Apply full composition actions: layouts for each template format (CompositionLayoutHtml / CompositionLayoutRtf / CompositionLayoutPureText) are stored within CompositionLayout. Therefore, each type of composition may contain the following sections:

Placeholders

Provided API enables inserting Active Directory variables directly into the chosen types of actions. Note that only PlaceholderSenderProperty type of placeholders may be inserted into actions. Furthermore, define the placeholder using its tag in the content of a template, e.g. {E-mail}.

C#
//Create an Insert disclaimer action
var actionInsertDisclaimer = new Settings.Actions.ActionApplyInsertDisclaimer();

//Within the Insert disclaimer action, set the composition’s layout to Plain Text
var compositionPureText = actionInsertDisclaimer.CompositionLayout.PureText;

//Compose the bottom (disclaimer) section, including an {E-mail} placeholder in the template composition
compositionPureText.Bottom.Content = "Sample disclaimer for {E-mail}";
Note Note

Not all actions support inserting of placeholders. Please refer to the Support for placeholders column in the table above to learn which actions support placeholders.

The following placeholders of the PlaceholderSenderProperty type are provided via API:

  • {City}

  • {Company}

  • {Country}

  • {Department}

  • {Description}

  • {Display name}

  • {E-mail}

  • {Fax}

  • {First name}

  • {Home phone}

  • {Initials}

  • {IP phone}

  • {Last name}

  • {Mobile}

  • {Notes}

  • {Office}

  • {P.O. Box}

  • {Pager}

  • {Phone}

  • {Postal code}

  • {State}

  • {Street}

  • {Title}

  • {Web page}

  • {ExchAttr1} - {ExchAttr15}

{Photo} placeholder

The {Photo} placeholder is not a simple text placeholder, and requires you to define the content of your signature/disclaimer template in a special way (HTML is the only supported format):

  • Create an action with an HTML composition layout (e.g. ActionApplyInsertSignature)

  • Insert numbered placeholders into your content, e.g. {Photo 1}, {Photo 2}.

  • Create and configure all placeholders using PlaceholderSenderPhotoComplex class. Set an ID and PhotoDimensions of your placeholders. You can also define the Width or/and Height of your photo in the content. PhotoDimensions allow you to define how your photo is adjusted to a specified Width or/and Height.

  • Add all created objects to the collection of complex placeholders.

  • Add the action to a rule.

  • Create a snapshot and add a new rule.

  • Upload the snapshot to SettingsStorage.

Here is a complete example of creating two {Photo} placeholders. Of course you can use any number of placeholders.

C#
//Create a new rule
var rule = new Settings.RuleDesc();

//Assign the rule's name and enable it
rule.Name = "Signature with photo";
rule.Active = true;

//Create an Insert signature action
var actionInsertSignature = new Settings.Actions.ActionApplyInsertSignature();

//Within the Insert signature action, set the composition layout to HTML
var compositionHtml = actionInsertSignature.CompositionLayout.Html;

//Add the {Photo 1} and {Photo 2} placeholder tags to the template composition
compositionHtml.Bottom.Content = "<html><body><p>Signatue {Photo 1} | {Photo 2}</p></body></html>";

//Create and configure the {Photo 1} placeholder (adjust dimensions to a specified width and height)
var photoPlaceholder1 = new ER.Shared.Placeholders.PlaceholderSenderPhotoComplex();
photoPlaceholder1.ID = 1;
photoPlaceholder1.Width = 100;
photoPlaceholder1.Height = 100;
photoPlaceholder1.PhotoDimensions = ER.Shared.Placeholders.EnumPictureDimensions.AdjustWidthAndHeight;

//Create and configure the {Photo 2} placeholder (use the original dimensions)
var photoPlaceholder2 = new ER.Shared.Placeholders.PlaceholderSenderPhotoComplex();
photoPlaceholder2.ID = 2;
photoPlaceholder2.PhotoDimensions = ER.Shared.Placeholders.EnumPictureDimensions.Original;

//Add the created placeholders to the collection of complex placeholders.
//Complex placeholders are those which require additional information (not simple text placeholders).
compositionHtml.Placeholders.Add(photoPlaceholder1);
compositionHtml.Placeholders.Add(photoPlaceholder2);

//Add the Insert signature action to the rule
rule.Actions.Add(actionInsertSignature);

//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

Conditions and exceptions - learn which conditions/exceptions can be defined in rules and implemented into a custom app via the provided API.