Mello's IT Musings

<#
.SYNOPSIS
Get-AttachmentFromEmail.ps1 will use Exchange Web Services to search the inbox of a given mailbox associated with an SMTP Address for any emails with attachments that are similar to the subject specified. If found all attachments in the emails found will be saved to the specified path. Options include the ability to search for just emails that arrived today, a search for an exact subject match, the ability to automatically unzip *.zip files, and the ability to delete the emails once the attachments have been successfully downloaded. The script also supports using impersonation to access a mailbox not belonging to the run time user
.DESCRIPTION
Before attempting any work the script checks for the existence of the EWS managed API, if it cannot be found the script will send an error to the console and to the email address specified to receive error reports
Once the EWS managed API is loaded a connection to Exchange is made to the mailbox of the current runtime user or using impersonation to connect to a mailbox of another user. Once connected the total items of in the mailbox being worked is found, this will be used to ensure the entire inbox is searched when looking for the email in question.
Then a search query is built to look for the following
1. Any email with a subject similar to the subject specified
a. The –ExactSearch parameter will search for emails with a subject that exactly matches the one specified
2. That also has attachments
This search will return all emails that match this query in the inbox, conversely the –TodayOnly switch can be used to return only emails matching the runtime date (e.g. 10/1/2013)
If any emails are found then the attachments are saved to the specified path (overwriting any files with the same name), if the path is not accessible then the script will send an error to the console and to the email address specified to receive error reports.
If the switch –UnZipFiles is used and the email attachments are indeed zip files then the script first copy the zip files to the destination path specified, un-compress the contents, and delete the zip file
If the switch –DeleteEmail is used then after all the attachments have been downloaded the emails found will be moved to the Deleted folder on the mailbox in question. 
.PARAMETER EmailSubject
The exact subject of the email that the script will search for
.PARAMETER SavePath
The local or network path the attachments found will be save to
.PARAMETER SMTPAddress
The SMTP address of the of the mailbox that the script will search for regardless if it's the current runtime user or a different user
.PARAMETER DeleteEmail
If specified any email found and it’s attachments successfully saved will be moved to the deleted folder. 
.PARAMETER TodayOnly
If specified only emails found that match the Day, Month, and Year of the current script runtime will be returned by the inbox search 
.PARAMETER ExactSearch
By default the script will search for any email matching any of the terms in the subject being searched for, when using this parameter the script will look for emails with a subject that exactly matches the subject being searched for
.PARAMETER UnZipFiles
If any attachments found are zip files you can specify that the script extract the files within the zip file and store them at the specified location instead of the zip file itself
.PARAMETER EwsUrl
Instead of using auto discover you can specify the EWS URL
.PARAMETER ExchangeVersion
Specify the Exchange Version the EWS service should use, the default is "Exchange2010_SP2"
.PARAMETER IgnoreSSLCertificate
Used to ignore any SSL certificate errors encountered when using EWS
.PARAMETER EWSManagedApiPath
Used to specify the path for the EWS Managed API, the default is C:\Program Files\Microsoft\Exchange\Web Services\1.2\Microsoft.Exchange.WebServices.dll
.PARAMETER EWSTracing
Used to turn on EWS tracing for troubleshooting
.PARAMETER ImpersonationUserName
The Username of the account to user for impersonation
.PARAMETER ImpersonationPassword
The Password of the account to user for impersonation
.PARAMETER ImpersonationDomain
The Domain of the account to user for impersonation
.PARAMETER EmailFrom
The SMTP address error emails will come from
.PARAMETER EmailErrorsTo
The SMTP address error emails will go to
.PARAMETER SMTPServer
The SMTP address server used to send error emails 
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Important Attachment” –SavePath “\\FileServer\Email Attachments” -SMTPAddress John.Doe@company.com
 
Description
-----------
Will use the runtime account to access and search the mailbox associated with "John.Doe@company.com" for any emails in the inbox with a subject like “Important Attachment” and save the attachments to \\FileServer\Email Attachments
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Important Attachment” –SavePath “\\FileServer\Email Attachments” -SMTPAddress John.Doe@company.com -ExactSearch –UnZipFiles 
 
Description
-----------
Will use the runtime account to access and search the mailbox associated with "John.Doe@company.com" for any emails in the inbox with the exact subject of “Important Attachment” and save the attachments to \\FileServer\Email Attachments. If any of those attachments are zip files then the script will extract the contents of the zip files leaving only the contents and not the zip file
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Sales Results” –SavePath “C:\Email Attachments” -SMTPAddress John.Doe@company.com -DeleteEmail -TodayOnly 
 
Description
-----------
Will use the runtime account to access and search the mailbox associated with "John.Doe@company.com" for any emails in the inbox with a subject like “Sales Results” with the runtime date of today and save the attachments to \\FileServer\Email Attachments. Once the attachments have been saved then move the email to the delete items folder
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Important Attachment” –SavePath \\FileServer\Email Attachments -SMTPAddress differentUser@company.com –ImpersonationUserName ServiceMailboxAutomation –ImpersonationPassword “$*fnh23587” –ImpersonationDomain CORP
 
Description
-----------
Will search the mailbox associated with “differentUser@company.com” using the account “ServiceMailboxAutomation” which will need the impersonation RBAC role to access the mailbox. The search will be for any emails in the inbox with a subject like “Important Attachment” and save the attachments to \\FileServer\Email Attachments. 
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Important Attachment” –SavePath \\FileServer\Email Attachments -SMTPAddress John.Doe@company.com –EmailFrom EmailTeam@company.com –EmailErrorsTo HelpDesk@company.com –SMTPServer mail.company.com
 
Description
-----------
Will use the runtime account to access and search the mailbox associated with "John.Doe@company.com" for any emails in the inbox with a subject like “Important Attachment” and save the attachments to \\FileServer\Email Attachments. If any errors are encountered then send an email from “EmailTeam@company.com” to “HelpDesk@company.com” using the SMTP server of “mail.company.com”
.EXAMPLE
PS C:\> .\Get-AttachmentFromEmail.ps1 -EmailSubject “Important Attachment” –SavePath \\FileServer\Email Attachments -SMTPAddress John.Doe@company.com –EwsUrl https://webmail.company.com/EWS/Exchange.asmx –EWSManagedApiPath "C:\Program Files\Microsoft\Exchange\Web Services\2.0\Microsoft.Exchange.WebServices.dll" -$ExchangeVersion Exchange2010_SP1 –IgnoreSSLCertificate -EWSTracing
 
Description
-----------
Will use the runtime account to access and search the mailbox associated with "John.Doe@company.com" any emails in the inbox that exactly match “Important Attachment” and save the attachments to \\FileServer\Email Attachments. Before connecting to the mailbox the EWS connection will use the following options
1. The EWS URL of https://webmail.company.com/EWS/Exchange.asmx
2. The EWS Managed API Path of "C:\Program Files\Microsoft\Exchange\Web Services\2.0\Microsoft.Exchange.WebServices.dll"
3. The Exchange version of "Exchange2010_SP1"
4. Ignore all SSL Certificate errors
5. Turn on EWS tracing
.INPUTS
System.String
You cannot pipe to this script
.OUTPUTS
NONE
.NOTES
AUTHOR: John Mello 
CREATED : 10/29/2013 
CREATED BECAUSE: To automate the retrieval, download, and deletion of a daily delivered email attachment 
.LINK
DSMS Script Storage location : \\Bala01\World\Technology\EnterpriseServices\PlatformServices\Directory and Messaging Services\Scripts
DSMS SharePoint Scripting Portal : http://techweb/ess/dci/dsms/scripting/default.aspx
DSMS PowerShell KB : http://techweb/ess/dci/dsms/scripting/powershellscripting/Home.aspx
#>
[CmdletBinding(DefaultParameterSetName="Default")]
Param(
[Parameter(Mandatory=$True,Position=0)]
[string]$EmailSubject,
 
[Parameter(Mandatory=$True,Position=1)]
[string]$SavePath,
 
[Parameter(Mandatory=$True,Position=3)]
[string]$SMTPAddress,
 
[Parameter(Mandatory=$false)]
[switch]$DeleteEmail,
 
[Parameter(Mandatory=$false)]
[switch]$TodayOnly,
 
[Parameter(Mandatory=$false)]
[switch]$ExactSearch,
 
[Parameter(Mandatory=$false)]
[switch]$UnZipFiles,
 
[Parameter(Mandatory=$false)]
[string]$EwsUrl = "https://webmail.susq.com/EWS/Exchange.asmx" ,
 
[Parameter(Mandatory=$false)]
[ValidateSet("Exchange2007","Exchange2007_SP1","Exchange2007_SP2","Exchange2007_SP3","Exchange2010","Exchange2010_SP1","Exchange2010_SP2","Exchange2010_SP3")]
[string]$ExchangeVersion = "Exchange2010_SP2",
 
[Parameter(Mandatory=$false)]
[switch]$IgnoreSSLCertificate,
 
[Parameter(Mandatory=$false)]
[string]$EWSManagedApiPath = "C:\Program Files\Microsoft\Exchange\Web Services\2.0\Microsoft.Exchange.WebServices.dll",
 
[Parameter(Mandatory=$false)]
[switch]$EWSTracing,
 
[Parameter(Mandatory=$True,ParameterSetName="Impersonation")]
[string]$ImpersonationUserName,
 
[Parameter(Mandatory=$True,ParameterSetName="Impersonation")]
[string]$ImpersonationPassword,
 
[Parameter(Mandatory=$false,ParameterSetName="Impersonation")]
[string]$ImpersonationDomain,
 
[Parameter(Mandatory=$False)] 
[string]$EmailFrom, 
 
[Parameter(Mandatory=$False)] 
[string[]]$EmailErrorsTo,
 
[Parameter(Mandatory=$False)] 
[string]$SMTPServer = "mailhost.susq.com"
)
 
#Region Functions
 
Function New-EWSServiceObject {
<#
.SYNOPSIS
Returns an EWS Service Object
.DESCRIPTION
Creates a EWS service object, with the option of using impersonation and/or An EWS URL or fall back to Autodiscover
.PARAMETER SMTPAddress
The SMTP address of the Exchange mailbox that is associated with the EWS object
.EXAMPLE
PS C:\powershell> New-EWSServiceObject -SMTPAddress "John.Doe@Company.com"
 
------------------
Description 
------------------
 
This will return and EWS object that uses impersonation with a specifed URL
#>
[CmdletBinding(DefaultParameterSetName="OtherUser")]
Param() 
 
Write-Verbose "Creating EWS Service connection object"
$EWSService = new-object Microsoft.Exchange.WebServices.Data.ExchangeService([Microsoft.Exchange.WebServices.Data.ExchangeVersion]::$ExchangeVersion)
 
If ($EWSTracing) {
Write-Verbose "EWS Tracing enabled"
$EWSService.traceenabled = $true
}
 
if ($IgnoreSSLCertificate){
Write-Verbose "Ignoring any SSL certificate errors"
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true };
} 
 
If ($SMTPAddress) {Write-Verbose "Creating service for the following address $SMTPAddress"}
Else {Write-Verbose "Creating service for the following runtime user $ENV:UserName"} 
 
Write-Verbose "Checking if the runtime or a seperate account will be used for impersonation"
If ($ImpersonationUserName -and $ImpersonationPassword) {
Write-Verbose "Secondary account for Impersonation specifed ($ImpersonationUserName)"
If ($ImpersonationDomain) {
#If a domain is presented then use that as well
$EWSService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials($ImpersonationUserName,$ImpersonationPassword,$ImpersonationDomain)
}
Else {
#Otherwise leave the domain blank
$EWSService.Credentials = New-Object Microsoft.Exchange.WebServices.Data.WebCredentials($ImpersonationUserName,$ImpersonationPassword)
}
Write-Verbose "Saving impersonation credentials for EWS service"
$EWSService.ImpersonatedUserId = New-Object Microsoft.Exchange.WebServices.Data.ImpersonatedUserId([Microsoft.Exchange.WebServices.Data.ConnectingIdType]::SmtpAddress, $SMTPAddress)
}
Else{
Write-Verbose "Runtime account specifed for impersonation ($ENV:Username)"
$EWSService.UseDefaultCredentials = $true 
}
 
#Set the EWS URL, the EWS URL is needed if the the runtime user is specifed since they may not have a mailbox
If ($EWSURL) {
Write-Verbose "Using the specifed EWS URL of $EWSURL"
$EWSService.URL = New-Object Uri($EWSURL)
}
Else {
Write-Verbose "Using the AutoDiscover to find the EWS URL"
$EWSService.AutodiscoverUrl($SMTPAddress, {$True})
}
#Now Return the Service Object
Return $EWSService
}
 
Function Send-ErrorReport {
<#
.SYNOPSIS
Used to create a one line method to write an error warning to the console, send an error email, and exit a script when an terminal error is encountered
.DESCRIPTION
Send-ErrorReport Takes a Subject and message body field and uses the Subject to write a warning messages to the console and as the email subject. It uses the body as the body of the email that will be sent. You can also specify and SMTP Server, From, and To address or set the default options. Once complete the script sends the exit command to script calling the function 
.PARAMETER Subject
The subject of the email to be sent and the warning message that is sent to the console
.PARAMETER body 
The body of the email sent
.PARAMETER HaltScript
Sends the Exit command to the script caling the function, used to report on terminating errors
.EXAMPLE
PS C:\powershell> Send-ErrorReport -Subject "can't load EWS module" -Body "can't load EWS module, verify this path : $EWSManagedApiPath" -HaltScript
 
WARNING: can't load EWS module
 
------------------
Description 
------------------
 
This will send an email through the specifed SMTP server, from and to the specifed addresses with the specifed subject and body and use the sbubject to write a warning message. Then function will stop the script that called it
#>
[CmdletBinding()]
Param(
[Parameter(Position=0,Mandatory=$true)]
[string]$Subject,
 
[Parameter(Position=1,Mandatory=$true)]
[string]$body,
 
[Parameter()]
[switch]$HaltScript
) 
 
Write-Warning $Subject
#Appened Script name to email Subject
If ($EmailFrom -and $EmailErrorsTo -and $SMTPServer) {
$Subject = "Get-AttachmentFromEmail.ps1 : " + $Subject
send-mailmessage -from $EmailFrom -to $EmailErrorsTo -smtpserver $SMTPServer -subject $Subject -Body ($body | Out-String) -BodyAsHtml
}
If ($HaltScript) {Exit 1}
}
 
#EndRegion
 
#Region PreWork
 
#Remove double qoutes from Subject, File Path, and SMTP address (just in case)
#Need to find a way around this
$EmailSubject = $EmailSubject -replace "`""
$SavePath = $SavePath -replace "`""
$SMTPAddress = $SMTPAddress -replace "`""
 
# Check if the save path is available, if not then exit the script
Try {Test-Path $SavePath -ErrorAction Stop | Out-Null}
Catch {Send-ErrorReport -Subject "Save path cannot be accessed" -body "Please the following user name <B>$($ENV:USERNAME)<?B>, has access to this path : <B>$SavePath</B>" -HaltScript}
 
# Check if EWS Managed API available, if not then exit the script
Try {Get-Item -Path $EWSManagedApiPath -ErrorAction Stop | Out-Null}
Catch {Send-ErrorReport -Subject "EWS Managed API path cannot be accessed" -body "Please verify the following EWS API path on <B>$($ENV:COMPUTERNAME)</B> : <B>$EWSManagedApiPath</B>" -HaltScript}
 
# Load EWS Managed API
[void][Reflection.Assembly]::LoadFile($EWSManagedApiPath);
 
#EWS requires double back whacks "\\" for each normal back whack "\" when
#it comes to the file path to save to
#E.g. C:\Windows\System32 needs to look like C:\\Windows\\System32
$EWSSavePath = $SavePath -replace "\\","\\"
 
#Create EWS Service
$EWSservice = New-EWSServiceObject
#EndRegion
 
#Region Main Program Work
#Attach to the inbox to find the total number of items
#This will be used on in the search query so that we search the entire inbox
$InboxID = new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox)
Try {$InboxFolder = [Microsoft.Exchange.WebServices.Data.Folder]::Bind($EWSservice,$InboxID)}
Catch {Send-ErrorReport -Subject "Account is not permissioned for Impersonation" -body "Please verify that the following account <B>$ImpersonationUserName</B> has the ability to impersonate <B>$SMTPAddress</B>" -HaltScript}
 
$NumEmailsToReturn = $InboxFolder.TotalCount
If ($InboxFolder.TotalCount -eq 0) {
Write-Warning "Inbox is empty, exiting script or the Runtime Account of $($ENV:USERNAME) does not have impersonation rights for $SMTPAddress"
Exit
}
 
#Create mailbox view
$view = New-Object -TypeName Microsoft.Exchange.WebServices.Data.ItemView -ArgumentList $NumEmailsToReturn
#Define properties to pull for each item in the view
$propertyset = New-Object Microsoft.Exchange.WebServices.Data.PropertySet (
[Microsoft.Exchange.WebServices.Data.BasePropertySet]::IdOnly,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::Subject,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::HasAttachments,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::DisplayTo,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::DisplayCc,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeSent,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::DateTimeReceived
)
#Assign view to porperty set
$view.PropertySet = $propertyset
#Define the search quuery
#An EWS exact search puts the search term in "" so if we need that then add the qoutes again)
If ($ExactSearch) {
$EmailSubject = "`"$EmailSubject`""
}
If ($TodayOnly) {$query = "Subject:$EmailSubject AND HasAttachments:True AND Received:today"}
Else {$query = "Subject:$EmailSubject AND HasAttachments:True"}
 
#Preform the search
$FoundEmails = $EWSservice.FindItems("Inbox",$query,$view)
#$FoundEmail = $items | Where-Object {$_.Subject -like $EmailSubject}
If ($FoundEmails) {
If ($UnZipFiles) {$ZipFileNames = @()}
Foreach ($Email in $FoundEmails) {
$emailProps = New-Object -TypeName Microsoft.Exchange.WebServices.Data.PropertySet(
[Microsoft.Exchange.WebServices.Data.BasePropertySet]::IdOnly,
[Microsoft.Exchange.WebServices.Data.ItemSchema]::Attachments
)
 
$EmailwithAttachments = [Microsoft.Exchange.WebServices.Data.EmailMessage]::Bind($EWSservice, $Email.Id, $emailProps)
Foreach ($File in $EmailwithAttachments.Attachments) {
Try {
#Just to be safe, remove any invaild characters from the attachment name
$FileName = $File.name -replace ("[{0}]" -f ([RegEx]::Escape([String][System.IO.Path]::GetInvalidFileNameChars())))
#Current can't handle Emails that are attacments, so we skip them
If ($File.contenttype -eq $null) {
Write-Warning "Attachment is an email, skipping"
$EMLAttachment = $TRUE
continue
}
Else {$EMLAttachment = $FALSE}
$File.load($EWSSavePath + "\\" + $FileName)
If (($FileName -like "*.zip") -and $UnZipFiles) {$ZipFileNames += $SavePath + "\"+ $FileName}
}
Catch {Send-ErrorReport -Subject "Attachment save path cannot be accessed" -body "Please verify the following path <B>$SavePath</B><BR>Full Error:<BR> $_" -HaltScript}
}
If ($DeleteEmail -and (-not $EMLAttachment)) {$Email.Delete("MoveToDeletedItems")}
Else {Write-Warning "DeleteEmail specifed but embedded EML file in email could not be downloaded"}
}
If ($UnZipFiles) {
Try {
$shell = new-object -com shell.application
$Location = $shell.namespace($SavePath)
foreach ($ZipFile in $ZipFileNames)
{
$ZipFolder = $shell.namespace($ZipFile)
$Location.Copyhere($ZipFolder.items())
Remove-item $ZipFile
}
}
Catch {Send-ErrorReport -Subject "Attachment save path cannot be accessed" -body "Please verify the following path <B>$SavePath</B><BR>Full Error:<BR> $_" -HaltScript}
}
}
#EndRegion