Script: New-WelcomeEmail.ps1 – Automatically Sending a ‘Welcome’ Email to All New User Accounts
Note: I’ve updated this script to address a couple of issues. The first is that if a scheduled task was configured for a time frame other than what was configured in the script itself, this would yield sporadic results. I’ve addressed this by writing a time stamp to the registry when the script runs. This removed the requirement of configuring the time in the script itself, and provides resiliency if the script runs at different times. Run the script once manually to set the configuration. I’ve also added some code that verifies the Exchange PowerShell snapin is loaded before attempting to run. If you’d like a feature added, please let me know in the comments below.
Note #2: If you’re using a server that’s not configured for the normal U.S. style time-date format, such as in the U.K., see Neil Hobson’s post at http://neilhobson.blogspot.com/2010/11/powershell-bug.html for information.
Anything that we can do to cut down on repetitive calls to the Help Desk staff is a good thing. When a new employee starts, there are always questions about ‘what is my email address?’, and ‘how do I get to email from the web?”. For years, admins have come up with sometimes complicated methods to send a new user a canned email that tries to answer these questions. With Exchange 2007 and Exchange Management Shell (PowerShell), we can do this quite easily. In fact, the hardest part is deciding what to include in the email message. Let’s get started..
Let’s read some info from the registry to see when was the last time the script ran. If it hasn’t run before, let’s set some initial info:
$strScriptName = $MyInvocation.MyCommand.Name if (!(Get-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name LastRun -EA SilentlyContinue)){ # this is the first time the script has run - let's create the registry key and value for future runs New-Item -path HKLM:\Software\Innervation -EA SilentlyContinue | Out-Null New-Item -path HKLM:\Software\Innervation\$strScriptName | Out-Null New-ItemProperty -path HKLM:\Software\Innervation\$strScriptName -Name "LastRun" -Value (Get-Date) -propertyType String | Out-Null write-host "Initial configuration completed." -ForegroundColor green } # get time stamp from registry so we know when it last ran $LastRun = Get-Date ((Get-ItemProperty -path HKLM:\Software\Innervation\$strScriptName -Name LastRun).LastRun) $ElapsedTime = ((Get-Date) - $lastrun).TotalSeconds
Let’s define some variables that we’ll use throughout the process.
$strMsgFrom = "Contoso HelpDesk " $strMsgTitle = "Welcome to Contoso!"
These set the From and Title for the email that we’ll send, as well as get today’s date, and the name of the script. Next, we create a new object to allow sending SMTP email:
$SMTPClient = New-Object Net.Mail.SmtpClient("localhost")
We can replace “localhost” with the IP address of a remote hub transport server if the script is not running on a hub transport server.
Next, we get a list of mailboxes that we need to send the email to. We’ll use a scheduled task to actually run the task. I run mine every 4 hours, but the code doesn’t care how often it runs. It will use the time stamp established above to email all mailbox created since then. We also want to avoid any mailboxes that are disabled. So our query looks like this:
$MBXArray = @(Get-Mailbox -ResultSize Unlimited | ? {($_.WhenCreated -gt (Get-Date).AddSeconds(-$ElapsedTime)) -and ($_.ExchangeUserAccountControl -ne "AccountDisabled")})
We now have an array, $MBXArray, that contains all of the mailboxes that we’ll email. We now cycle through the array via ForEach, and begin to assemble a personalized email message to each user. $mailbox holds the current account in the loop, so we can pull specific info for each user. Note that the text in $strBody is completely arbitrary – you can include whatever you want. Here’s a sample of one I did for a recent client:
ForEach ($mailbox in $MBXArray ) { $strMsgTo = $mailbox.PrimarySMTPAddress $strMsgBody = "Hello, "+$mailbox.DisplayName+", and welcome to the Contoso family! Please keep this email for future use. It contains vital information. -------------------------------------- Username and password -------------------------------------- Your network username is '"+$mailbox.SamAccountName+"'. Use your username and password to login to the network. Your password should NEVER be shared with anyone except the I.T. department, and only then when requested. Please do not write it down on anything that can be seen by your coworkers. You will be prompted to change it regularly. -------------------------------------- Email -------------------------------------- Your email address is '"+$mailbox.PrimarySMTPAddress+"'. To access your email, calendar, contacts, and tasks from outside of the building, such as from home, you can do so from any Internet connected computer. Simply open Internet Explorer and go to the Outlook Web Access (OWA) page at https://mail.contoso.com/ and log in using your username and password. Please note the 's' in https. If you’d like to have access to your email and contacts from your cell phone, you will need a cell phone that has Windows Mobile 5 or later, or an Apple iPhone. Blackberry phones are not supported. Instructions for configuring your device can be found in the Frequently Asked Questions (FAQ) section of the Contoso Intranet at https://intranet.contoso.com/helpdesk/Lists/SupportFaq/AllItems.aspx -------------------------------------- Contact information -------------------------------------- Once you’re situated, please go to http://directory/DirectoryUpdate and update your information. Log in using your username and password. It’s important that you update your information anytime something changes, such as title, department, phone number, etc. This information is used in various systems and applications, and is your responsibility to keep up to date. -------------------------------------- Computer, Email, and Internet policies -------------------------------------- Contoso, Inc. provides a computer for your work tasks. The use of personally owned computers and related equipment is not permitted on our network. Additional information about use of Contoso computers, email, Internet, etc. can be found in the Employee Handbook located in the HR section of the intranet at https://intranet.contoso.com/hr/ -------------------------------------- Technical assistance -------------------------------------- Should you need technical assistance, please check the Frequently Asked Questions (FAQ) section of the Contoso Intranet at https://intranet.contoso.com/helpdesk/Lists/SupportFaq/AllItems.aspx. If you cannot find an answer there, submit a Service Request on the Contoso intranet at https://intranet.contoso.com/helpdesk. If you are unable to access the intranet site, only then should you email HelpDesk@contoso.com. It is monitored by the whole IT department, and will ensure your issue is resolved in a timely manner. Thank you, and, again, welcome to Contoso! The Information Technology Department"
As you can see, we insert the user’s actual account name, email address, etc since that info is available in the ForEach loop. The message is just plain text, so spacing is preserved. URLs will be clickable links as well. Note: You’ll want to pay close attention to quotes and variables, as having an extra or missing quote can cause an error.
Now we actually send the message:
$SMTPClient.Send($strMsgFrom,$strMsgTo,$strMsgTitle,$strMsgBody) } # update registry here with a fresh time stamp Set-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name "LastRun" -Value (Get-Date) | Out-Null
We’ll run this script on a hub transport server. So take the script, available in the DOWNLOAD section below, and save it in your \scripts folder. You’ll also need an Exchange receive connector that will accept email sent from PowerShell scripts. For that, see Creating a receive connector to use for sending email from PowerShell. Now, schedule a task to run every 4 hours using the info in Running PowerShell scripts via Scheduled Tasks.
Point of interest: In the text I send to the users, you’ll see a link to the Directory Update (http://directory/DirectoryUpdate in the example above). This is for Directory-Update, a VERY lightweight ASP app developed by fellow MVP and author Jim McBee and another developer. It’s completely customizable, and allows users to update selected fields of their AD account to help keep the Global Address List (GAL) current. It is worth the small cost, and really helps you keep the GAL full of correct info. I have another PowerShell script that checks AD account fields, and when it finds empty fields (phone number, title, etc), it sends them an email with a link to the Directory-Update web page. Combine that with Automatically updating the Global Address List with mobile numbers from Exchange ActiveSync and it’s like a self-cleaning oven!
Installation
Execution Policy: Third-party PowerShell scripts may require that the PowerShell Execution Policy be set to either AllSigned, RemoteSigned, or Unrestricted. The default is Restricted, which prevents scripts – even code signed scripts – from running. For more information about setting your Execution Policy, see Using the Set-ExecutionPolicy Cmdlet.
Donations
I’ve never been one to really solicit donations for my work. My offerings are created because *I* need to solve a problem, and once I do, it makes sense to offer the results of my work to the public. I mean, let’s face it: I can’t be the only one with that particular issue, right? Quite often, to my surprise, I’m asked why I don’t have a “donate” button so people can donate a few bucks. I’ve never really put much thought into it. But those inquiries are coming more often now, so I’m yielding to them. If you’d like to donate, you can send a few bucks via PayPal at https://www.paypal.me/PatRichard. Money collected from that will go to the costs of my website (hosting and domain names), as well as to my home lab.
Download
v1.3 – 02-24-2013 – New-WelcomeEmail.v1.3.zip
ScriptImages.zip – image files used in emails
Changelog
See the changelog for this script for information on versions and what’s included/addressed in each.
First of all – excellent work; I have implemented a deviation of this script in our current messaging environment. The major changes I made was to log to the event log instead of the console, as well rewriting the mailbox retrieval logic:
[DateTime]$LastRun = Get-Date ((Get-ItemProperty -path HKLM:\Software\Sauer-Danfoss\$strScriptName -Name LastRun).LastRun) -Format s
if ($Verbose) { write-eventlog -logname application -source $strScriptName -eventID 5 -entrytype Information -message “Last run time: $LastRun”}
Set-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name “LastRun” -Value (Get-Date -Format s) | Out-Null
Get-Mailbox -ResultSize Unlimited -Filter {(IsResource -eq $false) -and (IsShared -eq $false)} | ? {($_.WhenMailboxCreated -gt $LastRun) -and ($_.ExchangeUserAccountControl -ne “AccountDisabled”)}
You will notice that I’ve changed WhenCreated to WhenMailboxCreated as mailboxes are not necessarily created at the same time as the mailbox. Also, I removed the ElapsedTime logic, as it was redundant (you can compare WhenMailboxCreated directly to a timestamp), and finally, moved adding the new timestamp to the registry to before the mailboxes are enumerated, as there would otherwise be a gap during the time it takes to enumerate all mailboxes.
I’d be happy to send you a copy of my script if you would like to take a look at the changes.
Again, thank you for your inspiration!
Sure, I’d love a copy. My email should be in the comment block in the beginning of the script.
As for moving the lastrun timestamp, the only reason I didn’t do it that was was in case of an error that causes the script to stop. I wait till the end to make sure everything was successful. But I can see your point.
Larry can you send me a copy of the script that Pat send you?
Couple of points…
When entering the message body into $strmsgbody, I found it only works with linebreaks rather than carriage returns… (i.e. Shift-Return instead of Return) at the end of each line. If I entered the text with “proper” carriage returns at the end of each line, powershell does not like it!
Also, rather than entering all of the body text in the script, I wanted to give the ability to simply maintain a single text file somewhere on the network, and pull it in with get-content… This works fine to a point, but it does not preserve the formatting in the text file at all… neither linebreaks or carriage returns are honoured, and the content is rendered as a single line.. – any ideas how to improve that?
And lastly, rather than running a scheduled script, I plan to use the extension agent and put this into the scriptingagentconfig.xml file for the new-mailbox and enable-mailbox cmdlets so that the mail is generated automatically for all new mailboxes AS they are created…
just a quick question, does this work for new users that were copied from an existing one?
I mean, I implemented this and it works fine if I create a new user from EMC, but if a copy an user in AD and then create it on EMC doesn’t work, any idea?
Yes, it should work for any newly created user.
Hi, thanks för at great script. In the changelog v1.3 i mentioned, but i cannot find it to download. The link points to v1.2 or am i missing something?
yes… no version 1.3 for download…
Okay, just posted the file that should be 1.3. Try it out.
This does not work for exchange 2010.
Is there away to make it work for exchange 2010?
It does work with Exchange 2010. And 2013.
Can you help me out then?
This script was written using 2010. If you have a properly configured receive connector, it will work fine.
I found the problem
$MBXArray = @(Get-Mailbox -ResultSize Unlimited | ? {($_.WhenCreated -gt (Get-Date).AddSeconds(-$ElapsedTime)) -and ($_.ExchangeUserAccountControl -ne “AccountDisabled”)})
This part does not get any results.
Run just by itself, it won’t return anything. That’s because there is a variable in that line that’s empty when run by itself. If it’s run via the script, then it’s only going to show users created since the last time the script ran (it uses a time stamp from the registry).
If you open Exchange Management Shell and run a wide check, using something like
$LastRun = (Get-Date).AddDays(-1000)
$ElapsedTime = ((Get-Date) – $lastrun).TotalSeconds
$MBXArray = @(Get-Mailbox -ResultSize Unlimited | ? {($_.WhenCreated -gt (Get-Date).AddSeconds(-$ElapsedTime)) -and ($_.ExchangeUserAccountControl -ne “AccountDisabled”)})
$MBXArray
Does it list anything? It should list all users created in the last 1000 days.
Yes it shows results.
Hmm.. is the problem then in the connector. Do i really need a Internal connector. Because when i use send-mailmessage it works. Is the connector still a problem?
I use Send-NewUserWelcome.zip and i modifed it. No errors. I created a new mailbox and new user but still no mail. I checked the registry key and it was created.
if (-not((Get-PSSnapin) -match “Microsoft.Exchange.Management.Powershell.E2010”)){ Add-PSSnapin Microsoft.Exchange.Management.Powershell.E2010 }
$strScriptName = $MyInvocation.MyCommand.Name
if (!(Get-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name LastRun -EA SilentlyContinue)){
# this is the first time the script has run – let’s create the registry key and value for future runs
New-Item -path HKLM:\Software\Innervation -EA SilentlyContinue | Out-Null
New-Item -path HKLM:\Software\Innervation\$strScriptName | Out-Null
New-ItemProperty -path HKLM:\Software\Innervation\$strScriptName -Name “LastRun” -Value (Get-Date -Format G) -propertyType String | Out-Null
write-host “Initial configuration completed.” -ForegroundColor green
}
# get time stamp from registry so we know when it last ran
$LastRun = Get-Date ((Get-ItemProperty -path HKLM:\Software\Innervation\$strScriptName -Name LastRun).LastRun)
$ElapsedTime = ((Get-Date) – $lastrun).TotalSeconds
$strMsgFrom = “Administrator ”
$strMsgTitle = “Welkom bij Company!”
$SMTPClient = New-Object Net.Mail.SmtpClient(“*.*.*.*”)
$MBXArray = @(Get-Mailbox -ResultSize Unlimited | ? {($_.WhenCreated -gt (Get-Date).AddSeconds(-$ElapsedTime)) -and ($_.ExchangeUserAccountControl -ne “AccountDisabled”)})
ForEach ($mailbox in $MBXArray ) {
$strMsgTo = $mailbox.PrimarySMTPAddress
$strMsgBody = “Beste, “+$mailbox.DisplayName+”, welkom bij Company! Deze email is persoonlijk. Het bevat gevoelige informatie.
————————————–
Gebruikersnaam en wachtwoord
————————————–
Jouw netwerk gebruikersnaam is ‘”+$mailbox.SamAccountName+”‘.
De Support Afdeling”
$SMTPClient.Send($strMsgFrom,$strMsgTo,$strMsgTitle,$strMsgBody)
}
# update registry here with a fresh time stamp
Set-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name “LastRun” -Value (Get-Date -Format G) | Out-Null
Do i need to add or change the SMTPclient line?
$SMTPServer = “*.*.*”
$SMTPClient = New-Object Net.Mail.SmtpClient($SmtpServer)
Is there anyway i can put html in the body?
It is working. I changed your script a little bit. I made the mail more html. But thnx for your nice script.
Your script is running great but it is sending emails to existing users also. Everytime this script runs, it sends email to new user as well as existing user. Would you please help?
Thank You for this great script. However, I need some help in modifying this script.
1. Can we send a PDF attachement along with this Welcome email, if so how?
2. We need to send this PDF attachment to only new mailbox users who have “EX” in the “Description” field in the Active Directory user properties. Is this possible?
Thank You in advance. Kindly help.
Send-MailMessage (http://technet.microsoft.com/en-us/library/hh849925.aspx) does support an -attachments parameter that can be used to send the .pdf files.
Since the script doesn’t look at AD user properties, it’s not possible with this script without a bunch of extra work.
would anybody be able to assist in setting this up I am a little confused here. I downloaded the script and saved it to my script folder then ran .\New-WelcomeEmail.ps1 -Install however the only thing it did was ask me for my password and created the scheduled task. It did not however go through the parameters and ask me for things like IP address of email server, or OWA URL etc. Am I missing something, I think this script would be great if I could get it to run and test it. Any guidance is greatly appreciated.
It’s not supposed to ask for those things. You have to manually enter that info in the script.
ok thanks for the quick response. SO the only way to test is by creating a new account and seeing if I get the email right?
Or the run it manually with the -PreviewUser option
Ok so I got it to run and send the email great sript by the way, but instead of sending the email to the newly created mailboxit is sending it to my account which is who the scheduled task is to run under. The email contains all the correct information for the newly created account i.e. testuser domain name and email address but it just keep sending it to me and I dont know where its getting my email address from. How can I get this to send it to the new mailbox instead.
please disregard previous comment I figured out where I had put my email address. Sorry
One last question and I think I am all set. For testing purposes I set the scheduled task to run every 5 minutes, the email is created and sent to the correct email address fine but for whatever reason it sends it over and over to the same user every time that tasks run. Shouldn’t it identify it sent it already to this test user?
On the machine you’re running it on, look in the registry at HKLM:\Software\Innervation\New-WelcomeEmail.ps1 and see if there is a LastRun timestamp.
yes there is but the timestamp is from early this morning and it has ran multiple times since then but seems like the timestamp is not updating. However I also see LastRun under HKLM:\Software\Innervation and the timestamp there is updating, I tested it by running the task again manually and it changed it once it completed.
I fixed it the command at the end Set-ItemProperty HKLM:\Software\Innervation\$strScriptName -Name “LastRun” -Value (Get-Date) | Out-Null was updating HKLM:\Software\Innervation instead. So I changed that line to Set-ItemProperty HKLM:\Software\Innervation\New-WelcomeEmail.ps1 -Name “LastRun” -Value (Get-Date) | Out-Null and I received only one email at it has ran at least twice. I’m not sure why it didnt identify the variable correctly but thanks. Again thanks for all the help and awsome script been looking for something like this for a while.
Ah – so that’s an issue on my end. I stopped using something called Hungarian notation, which required me to change the names of some variables. So
Set-ItemProperty HKLM:\Software\Innervation\$strScriptName
at the end of the script should be
Set-ItemProperty HKLM:\Software\Innervation\$ScriptName
Sorry about that!
No worries I didnt even catch that myself. Thanks again
I am seeing an odd issue with the script and I wanted to see if you or anyone else have experienced it as well. Right now the script works perfectly BUT only if I create the user in AD then add the mailbox through the EMC i.e New Mailbox –> Existing user, look for the newly created user and complete the wizard. Once the script runs it finds the newly created mailbox and sends the email fine. However if I create the new user using the EMC from the beginning the email is never sent, the script never sees this newly created account from the EMC. When I run the following in EMS (Get-Mailbox -ResultSize Unlimited | ? {($_.WhenCreated -gt (Get-Date).AddDays(-1)) -and ($_.ExchangeUserAccountControl -ne “AccountDisabled”)}) I do see the all three accounts that I created including the one from within the EMC. Anyone else seen this?
Pat – I just ran across this and it looks like it will be a great solution for us. I have one question, however, before I implement it. We are a construction company, and over the lifespan of a computer it will serve many different users. I am concerned that writing the timestamp in HKLM will only notify the first, new user of a machine. Would the best remedy be to just use HKCU instead of HKLM or I am I misunderstanding how the script runs? Thanks!
This script does not write to the local user’s computer registry. It time stamps the registry that the script runs on (server). This is a method to ensure that you capture everyone that needs to be emailed since the last time it ran.
Pat – thanks for the quick response. One more question. Will the script work with Office 365? We have a hybrid setup so I can relay mail off of our on-premises Exchange box, but all of our mailboxes are in the cloud.
It should. As long as you can hit a receive connector that will accept the messages.
I know this script not seems updated since v.1.3 But I added the attachments function to it.
Just add tje next line before the command Send-Mailmessage
Get-ChildItem “c:\scripts\files”| Where {-NOT $_.PSIsContainer} | foreach {$_.fullname} |
So add this command will result in
Get-ChildItem “c:\scripts\files”| Where {-NOT $_.PSIsContainer} | foreach {$_.fullname} | Send-MailMessage -To $UserEmail -Subject “Welcome to $company!” -Body $emailbody -From $EmailFrom -SmtpServer $EmailServer -Priority High -BodyAsHTML
Where c:\scripts\files is the directory where all the attached file is stored and you want to send it with the email.
I’ve tested it on Exchange 2013 and it’s works perfectly
Great script, used previously with exchange 2010
I am now trying to implement with O365 hybrid. Mailboxes in cloud. I have tried making a remote connection to exchange online, but no success.
Would appreciate it if you have any more thoughts.
Thanks
I have no idea. I haven’t looked at that script in ages, and don’t have the bandwidth to test.
Understandable. Thanks for replying.
HI I have exchange two 2013 server on prod.But only installed CAS one of server.
Now I tried send automatically mail to new users but not work.
Please give me any advice.
HI I have exchange two 2013 server on prod.But only installed CAS one of server.
Now I tried send automatically mail to new users but not work.
Please help me.
I use this script
Add-PSSnapIn Microsoft.Exchange.Management.PowerShell.Admin
Get-Mailbox | where {$_.WhenCreated -gt (get-date).adddays(-1)} | foreach{
$alias = $_.Alias
$name = $_.Name
$domain = “domain name”
$Smtp = “hostname”
$from = “username@domain.name”
$Subject = “Welcome to OUR Company”
$Body = “Welcome text”
$enc = New-Object System.Text.utf8encoding
Send-MailMessage -From $from -To $alias@$domain -Subject $Subject -Body $Body -Encoding $enc -SmtpServer $Smtp -BodyAsHtml
}
Hi Pat,
Does it work on exchange server 2016 version?
Best regards.