Managed AutoResponder Notifications

Posted on December 13, 2021 by Michel de Rooij

A long overdue blog on a solution which was created per request of an Exchange fellow. The original scenario is an organization spinning off, thereby changing their primary e-mail domain. They wanted to inform relations and partners using the old e-mail addresses of this change. However, this solution might also be helpful to organizations after merger and acquisitions or rebranding.

For the sake of the example, let us suppose Fabrikam was acquired by Contoso. Targeted mailboxes are migrated from the Fabrikam tenant to the Contoso tenant. Fabrikam will contain Mail-Enabled Users forwarding messages to their Contoso mailbox counterparts. The migrated mailboxes now hosted in Contoso will be configured to send notifications to senders which sent mail to the old Fabrikam address.

While organizations can resort to 3rd party tools to set up an Exchange Transport Rule with a generic message, a little script might also do the job, offering a more granular and controlled solution.

Solution
The scripted solution is available on GitHub here. It will configure an Inbox rule on the targeted Exchange mailbox(es), which would be the new/migrated mailbox. The rule will trigger when messages land in the inbox which were sent to a specific e-mail address, i.e. the previous e-mail address. It will send out an automatic response, which can consist of a custom subject, message body with an optional embedded image. The configuration of the response is defined in an customizable external XML file:

<?xml version="1.0" encoding="ISO-8859-1"?>  
<config>
  <rule>Contoso Autoresponder</rule>
  <subject>Please update your email recipient to Contoso</subject>
  <body>Dear Sender,

Thank you for your message. Fabrikam is now a whole Contoso subsidiary, and the fabrikam.com e-mail address will change to contoso.com. Your e-mail was forwarded to my new e-mail address. 

Please update contact information, distribution lists, etc. to update [OldMail] e-mail references with my new [Identity] e-mail address. 
 
[logo] 
The Contoso Corporation is a multinational business with its headquarters in Paris.</body>
  <logo>Contoso.png</logo>
</config>

The elements that can be used in the config are:

<rule> defines the name of the Inbox rule to be created. When the script runs, it will update any existing previously created inbox rules of the same name.
<subject> defines the subject of the response.
<body> defines the message body. You can use the following macros here:
- [OldMail] will get replaced with the original e-mail address.
- [Identity] will get replaced with the new e-mail address.
- [Logo] will get replaced with the embedded image.
Optionally, <logo> refers to the file name of the image to embed.

Requirements
To run the script, you need the following:

Exchange Server 2013 SP1 or later, or Exchange Online.
Exchange Web Services (EWS) Managed API 2.21 or later (how to, NuGet package exchange.webservices.managed.api).
When using modern authentication or OAuth2, the MSAL library is required (NuGet package Microsoft.Identity.Client). Also, you need to have registered an App in Azure Active Directory with sufficient permissions (e.g. full_access_as_app). After registering the app, Tenant ID, Application ID and certificate or secret is what you need to use with the script to run successfully.
In addition to installing the NuGet packages, you can also store their DLLs in the same folder as the script for portability.

Usage
The syntax to run the script is as follows:

.\Set-AutoResponderNotification.ps1 -Identity <Identity> -TemplateFile <File> [-TenantId <TenantId> -ClientId <ClientId> [-CertificateThumbprint <ThumbPrint>] [-CertificateFile <File> -CertificatePassword <SecureString>] [-Secret <SecureString>]] [-Credentials <PSCredential>] [-Clear] [-Overwrite] [-Impersonation] [-TrustAll]

The available parameters and switches are as follows:

Identity specifies one or more e-mail addresses of mailboxes to process. Identity supports the pipeline (see examples).
OldMail specifies one or more old e-mail addresses to use when configuring the autoresponder message. When specifying multiple identities,
the number of OldMail entries need to match the number of identities.
Server specifies the Exchange Web Services endpoint, for example outlook.office365.com for Exchange Online. When omitted, Autodiscover will be used.
Impersonation to use impersonation when accessing the mailbox. When using modern authentication, impersonation is mandatory.
TrustAll to accept all certificates including self-signed certificates.
TenantId specifies the ID of the Tenant when using a mailbox hosted in Exchange Online.
ClientId to specify the Application ID of the registered application in Azure Active Directory.
Credentials to specify the Basic Authentication credentials for on-premises usage or against Exchange Online when modern authentication is not an option.
CertificateThumbprint is the thumbprint of the certificate to use for modern authentication. The certificate with the public key needs to stored with the registered application for authentication. The certificate with the private key should be present in the local certificate store.
CertificateFile and CertificatePassword can be used to specify a certificate file to use. The file should contain the private key; the password protecting the certificate file can be specified using CertificatePassword as a secure string.
Secret can be used to specify the secret to authenticate using the registered application. The secret needs to be provided as a secure string.
Template
specifies the XML template file to use when configuring or clearing the autoresponder inbox rule. The format has explained above.
Clear specifies if any you want to remove the inbox rules with name specified in the template. Use this when you want to remove autoresponder rules from mailboxes. When using Clear, you don’t need to specify OldMail.
Overwrite specifies if any existing inbox rules with name specified in the template should be overwritten. When omitted, the script will skip processing
mailboxes with inbox rules with conflicting names. Use this when you want to configure the autoresponder only on mailboxes which do not have the rule.

Note that usage of the Verbose, Confirm and WhatIf parameters are supported.

Examples
Nothing more explanatory than an example. When we want to configure the autoresponder on a single mailbox, we can use something like:

Here, the autoresponder will get configured on the specified mailbox, triggering when mail has been sent to michel@fabrikam.com using the configuration defined in template.xml. Modern authentication will be used for authentication, using variables for Tenant, Client and in this case secret.

When you want to configure autoresponder for multiple mailboxes, you can for example use a CSV file. It needs to contain two elements which will be passed through pipeline, Identity and OldMail:

Identity,OldMail
philip@contoso.com,p.mortimer@fabrikam.com
francis@contoso.com,f.blake@fabrikam.com

After defining the response in a file template.xml, we can use this CSV to configure inbox rules on the Contoso mailboxes identified by Identity, triggering when mail is sent to their OldMail addresses:

Import-CSV -Path Users.csv | .\Set-AutoResponderNotification.ps1 -Server outlook.office365.com -Impersonation -TemplateFile .\Template.xml -TenantId <TenantId> -ClientId <ClientId> -Overwrite -CertificateThumbprint <Thumbprint>

What will happen is that for every set of Identity and OldMail, the mailbox specified by Identity will be configured with an inbox rule. When an existing rule is found, which is determined using the <rule> element in the XML template, it will get overwritten. The specified certificate will be picked from the local certificate store to authenticate against Tenant with TenantId, as application specified by ClientId.

Note that when the user opens Manage Rules & Alerts in Outlook, the configured inbox rule will be visible. This allows the user to remove it when it is no longer required. After a certain period, administrators can centrally remove these rules as well running the script using the Clear switch.

And finally, an example of how this may looks to senders when they receive an autoresponse message, using the sample configuration from the beginning of this article.

Application Access Policy
When using the script with modern authentication, you can leverage features such as conditional access to set boundaries for script usage. Also, you can configure application access policies to scope the registered app (script) to a subset of mailboxes. To accomplish this, assign an ApplicationAccessPolicy to the app.

To be more convenient in managing permissions, you can define a distribution group and assign the Application Access Policy with group scope (PolicyScopeGroupId). You then only need to add/remove members as you need to configure mailboxes.

More information about Application Access Policies here. Note that the permissions mentioned to not include full_access_as_app as permission, but it works.

EWS, why not Graph?
Microsoft already announced back in 2018 that development on Exchange Web Services will halt in and focus will shift to Graph. As part of this move, a more recent statement announced deprecation of some least-used API per March 2022, stimulating organizations to switch to using Graph. However, the organization looking for a solution wished for an automatic response with HTML as well as an embedded logo. Because of this, I had to use a template as a reply action.

But where Exchange Web Services supports reply with a template, Graph does not offer this functionality. So, until there is more feature parity between Exchange Web Services and Graph, or EWS goes completely out of service, solutions may still be forced to have a look at EWS for certain tasks.

Script Updates

Posted on June 9, 2014 by Michel de Rooij

A small heads-up for those not following me on Twitter of one of the other social media channels. Last week I made updates to the following three scripts:

Install-Exchange2013.ps1, version 1.72

Added CU5 support
Added KB2971467 (CU5 Disable Shared Cache Service Managed Availability probes)

Remove-DuplicateItems.ps1, version 1.3

Changed parameter Mailbox, you can now use an e-mail address as well.
Added parameter Credentials.
Added item class and size for certain duplication checks.
Changed item removal process
Remove items after, not while processing folder. Avoids asynchronous deletion issues.
Works against Office 365.

Remove-MessageClassItems.ps1, version 1.3

Changed parameter Mailbox, you can now use an e-mail address as well
Added parameter Credentials
Added parameter PartialMatching for partial class name matching.
Changed item removal process. Remove items after, not while processing folder. Avoids asynchronous deletion issues.
Works against Office 365.
Deleted Items folder will be processed, unless MoveToDeletedItems is used.
Changed EWS DLL loading, can now be in current folder as well.

Be advised I keep am overview of the scripts and their current versions with publish dates here.

Jetstress 2013

Posted on March 8, 2013 by Michel de Rooij

In the list of expected products to accompany Exchange 2013, Microsoft today released JetStress 2013, version 15.0.651.0.

Jetstress is your tool of choice to check the performance and stability of your storage design under load. It simulates Exchange I/O behaviour using Exchange 2013 patterns allowing you to verify dimensioning and validate performance expectations from a database perspective.

To run JetStress 2013 you need:

.NET Framework 4.5
ESE.DLL, ESEPerf.dll, ESEPerf.ini, ESEPerf.hxx (copy these from an Exchange 2013 installation source)

Note: The installer currently installs a shortcut named “Exchange JetStress 2010”, but it really is JetStress 2013.

You can download the Jetstress 2013 here.

NGN Exchange Event, Tips & Tricks Presentation

Posted on November 2, 2012 by Michel de Rooij

On October 31st, the NGN – a Dutch society for IT professionals – held its 3rd Exchange themed event, this time at The Reehorst in Ede (NL). Because of the recently released Exchange 2013 and all the news and related questions, we planned for a whole day of sessions and it was nice to see the turn up was nearly 100 IT professionals.

Since all people would still be on pre-2013 versions of Exchange, I figured a presentation using real-world Exchange 2010 Tips and Tricks might be more appropriate. I was glad a quick poll amongst the attendees showed a significant increase in Exchange 2010 deployments (around 80%) when compared to last year’s event, but as expected there’s still some Exchange 2007 and few Exchange 2003 out there.

I decided to stick with two deep-dive topics, which were Message Trackings Logs and Cmdlet Extension Agents. On those topics I went from basics to more advanced examples, hoping it would ignite people with no experience and people with experience could still pick up a thing or two.I’m still waiting for evaluation results, the only way to get feedback from these sessions apart from the occasional e-mail or tweet.

(picture by Dave Stork)

You can find my presentation here (partially Dutch) and the accompanying sample script on Message Tracking Logs here and the one on Cmdlet Extension Agents here (script); the ScriptingAgent.xml file can be downloaded here.

As always, these events are also a time to catch up with fellow Exchange people and discuss topics with attendees during the breaks. There were even Exchange fellows present who didn’t have a session, like Johan Veldhuis (MVP) and Maarten Piederiet (MCM); they did join in on the Q&A Panel.

The sessions and speakers were:

Introduction (Jaap Wesselius, MVP)
Building with Exchange 2013: Architecture (Dave Stork)
Exchange and Virtualisation (Jetze Mellema)
Exchange 2010 Tips & Tricks (Ashley Flentge, MCM & Michel de Rooij)
Exchange 2013 Coexistence and Migrations (Kay Sellenrode, MCM and MCA)
Exchange and Load Balancing (Jetze Mellema)
Q&A Panel

The NGN published all presentations in a single ZIP file which can be downloaded here. Unfortunately, NGN didn’t record the sessions so I can’t share those with you. They did record the Q&A Panel session; you can view it here (in Dutch):

PS: When you see references to “exchangedag”, like in the Twitter hashtag, you need to know “dag” means day in Dutch; it’s no form of professional deformation.

Adding Exchange Shell items to PowerShell ISE

Posted on October 25, 2012 by Michel de Rooij

I’ve become a fan of using the PowerShell Integrated Scripting Environment (PowerShell ISE) for creating, testing and debugging scripts, using breakpoints and step-by-step execution; features found in many development environments. Depending on the script I’m working on and for what customer or environment, I may need to add snap-ins or switch contexts, like connecting to Exchange Online.

One of the powerful features of ISE is that it allows customizing through the ISE object model. For example, you can explore ISE through the $psise object:

To add custom menu options to ISE, we’re going to add items to the submenu of $psISE.CurrentPowerShellTab.AddOnsMenu, which is “Add-ons”. An item needs to consist of:

Display Name, which is used for displaying the menu item;
Action, which can be a PowerShell cmdlet, scriptblock or function;
Optionally, you can assign a keyboard shortcut to the menu option.

To automatically load the custom entries after starting up ISE, we’re going to define the entries in our default ISE profile file, Microsoft.PowerShellISE_profile.ps1, which location is stored in $profile. The file doesn’t exist by default, so when required you can simply create the file in the proper location using notepad $profile.

In our example, we’ll add three entries:

Implicit Remoting to connect to Exchange using a static FQDN;
Loading the Exchange 2010 Snap-in and connecting to Exchange using Autodiscover (unsupported, will bypass RBAC);
Connecting to Exchange Online.

Note that the example won’t be using stored credentials and will let ISE prompt the user for credentials when required, which is perfectly fine if you need to access different Office 365 tenants for example.

Now, in the Microsoft.PowerShellISE_profile.ps1 file, add the following contents:

$psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add(
    "Connect to Exchange @ Contoso", {
        $ExSession= New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://exserver.contoso.com/PowerShell/ -Authentication Kerberos
        Import-PSSession $ExSession
    },
    "Control+Alt+1"
)
$psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add(
    "Connect to Exchange On-Premise", {
        Add-PSSnapin Microsoft.Exchange.Management.PowerShell.E2010
        . $env:ExchangeInstallPath\bin\RemoteExchange.ps1
        Connect-ExchangeServer –auto
            },
    "Control+Alt+2"
)
$psISE.CurrentPowerShellTab.AddOnsMenu.SubMenus.Add(
    "Connect to Exchange Online", {
        $o365Cred= Get-Credential
        $o365Session= New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.outlook.com/powershell/ -Credential $o365Cred -Authentication Basic -AllowRedirection
        Import-PSSession $o365Session
    },
    "Control+Alt+3"
)

After starting ISE you’ll see the Add-ons menu now contains three extra items:

When selecting “Connect to Exchange Online” (or pressing the configured keyboard shortcut), ISE will execute the associated code block; the progress is displayed in the output window. You will be prompted for credentials after which ISE will connect to Exchange Online and import the remote session.

After the session has been imported, you have the additional commands at your disposal in ISE and you can work on your scripts since they’ll be running in the context of the environment you’ve connected to.

Of course, this is just an example of what you can customize in ISE (pink background anyone?). For more information on customizing PowerShell ISE check here. If you’re new to PowerShell ISE, check here.