PSSendGrid.psm1
|
Function Remove-Diacritics { # remove al special characters [CmdletBinding()] param( [parameter(Position = 1)] [string]$Value ) $Value = $Value.Replace("ẞ", "ss") $TextWithoutDiacritics = [Text.Encoding]::ASCII.GetString([Text.Encoding]::GetEncoding("Cyrillic").GetBytes($Value)) if ($Value -ne $TextWithoutDiacritics) { Write-Verbose "Replaced $Value with $TextWithoutDiacritics" } $TextWithoutDiacritics } function New-AddressArray { # Create an array with all the address data [outputtype([array])] [CmdletBinding()] param( [parameter(Position = 0)] [string[]]$Addresses, [parameter(Position = 1)] [string[]]$Names ) $AllAddresses = @() $i = 0 if ( $Addresses.Count -eq 0) { Write-Verbose "No addresses found, moving on" } else { Write-Verbose "Found $($Addresses.Count) addresses" foreach ($AddressValue in $Addresses) { Write-Verbose "Processing Address $($i) Value: $($AddressValue)" try { $null = [mailaddress]$AddressValue } catch { Throw "Invalid email address: $AddressValue" } $AddressObject = [pscustomObject]@{ "email" = (Remove-Diacritics $AddressValue) } if ($Names.Count -gt $i) { $AddressObject | Add-Member -MemberType NoteProperty -Name "Name" -Value (Remove-Diacritics $Names[$i]) } Write-Verbose "Added Name $($AddressObject.Name) to AddressObject" $AllAddresses += $AddressObject # } $i++ } $AllAddresses } } Function Send-PSSendGridMail { <# .SYNOPSIS Send an email through the SendGrid API .DESCRIPTION This function is a wrapper around the SendGrid API. It is possible to send attachments as well. .PARAMETER ToAddress Emailaddress of the receiving end, multiple addresses can be entered in an array .PARAMETER ToName Name of the receiving end, multiple names can be entered in an array. When using multiple addresses, the ToName array must be in the same order as the ToAddress array. .PARAMETER FromAddress Source email address .PARAMETER FromName Source name .PARAMETER CcAddress Emailaddress of the CC recipient, multiple addresses can be entered in an array. .PARAMETER CcName Name of the CC recipient, multiple names can be entered in an array. When using multiple addresses, the CcName array must be in the same order as the CcAddress array. .PARAMETER BccAddress Emailaddress of the BCC recipient, multiple addresses can be entered in an array. .PARAMETER BccName Name of the BCC recipient, multiple names can be entered in an array. When using multiple addresses, the BccName array must be in the same order as the BccAddress array. .PARAMETER Subject Subject of the email .PARAMETER Body Body of the email when using plain text .PARAMETER BodyAsHTML Body of the email when using HTML .PARAMETER Token SendGrid token for the API .PARAMETER AttachmentPath Path to file(s) that needs to be attached. This can be a single string or an array of strings .PARAMETER AttachmentDisposition Attachment or Inline. Use inline to add image to HTML body .PARAMETER AttachmentID AttachmentID(s) for inline attachment, to refer to from the HTML. This can be a single string or an array of strings For multiple Attachments, the IDs should be in the same order as the attachmentPaths .EXAMPLE $Parameters = @{ FromAddress = "example@example.com" ToAddress = "example2@example.com" Subject = "SendGrid example" Body = "This is a plain text email" Token = "adfdasfaihghaweoigneawfaewfawefadfdsfsd4tg45h54hfawfawfawef" FromName = "Jane Doe" ToName = "John Doe" } Send-PSSendGridMail @Parameters ======= Sends an email from example@example.com to example2@example.com .EXAMPLE $Parameters = @{ Token = "API TOKEN" ToAddress = "example@example.com" BodyAsHTML = "<h1>MetHTML</h1><img src='cid:exampleID'>" ToName = "Example2" FromName = "Example1" FromAddress = "example2@example.com" AttachmentID = "exampleID" AttachmentPath = "C:\temp\exampleimage.jpg" AttachmentDisposition = "inline" Subject = "Test" } Send-PSSendGridMail @Parameters ======= Sends an email with an inline attachment in the HTML .EXAMPLE $Parameters = @{ FromAddress = "example@example.com" ToAddress = @("example2@example.com", "example3@example.com") cCAddress = "Example4@example.com" Subject = "SendGrid example" Body = "This is a plain text email" Token = "adfdasfaihghaweoigneawfaewfawefadfdsfsd4tg45h54hfawfawfawef" FromName = "Jane Doe" ToName = @("John Doe", "Bert Doe") } Send-PSSendGridMail @Parameters ======= Sends an email from example@example.com to example2@example.com and example3@example.com, with CC to Example4@example.com .LINK https://github.com/Ba4bes/PSSendGrid .LINK https://4bes.nl/2020/07/26/pssendgrid-send-email-from-powershell-with-sendgrid/ .NOTES Created by Barbara Forbes Script has been tested for Windows PowerShell and PowerShell 7. Only has been tested on Windows. @Ba4bes https://4bes.nl #> [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')] param ( [parameter(Mandatory = $True)] [string[]]$ToAddress, [parameter(Mandatory = $False)] [string[]]$ToName, [parameter(Mandatory = $True)] [string]$FromAddress, [parameter(Mandatory = $False)] [string]$FromName, [parameter(Mandatory = $False)] [string[]]$CCAddress, [parameter(Mandatory = $False)] [string[]]$CCName, [parameter(Mandatory = $False)] [string[]]$BCCAddress, [parameter(Mandatory = $False)] [string[]]$BCCName, [parameter(Mandatory = $True)] [string]$Subject, [parameter()] [string]$Body, [parameter()] [string]$BodyAsHTML, [parameter(Mandatory = $True)] [string]$Token, [parameter()] [ValidateScript( { Test-Path $_ })] [string[]]$AttachmentPath, [parameter()] [ValidateSet('attachment', 'inline')] [string]$AttachmentDisposition = "attachment", [parameter()] [string[]]$AttachmentID ) # Collect initial variables $StartVariables = (Get-Variable).Name Write-Verbose "Starting Function Send-PSSendGridMail" # Set body as HTML or as text if (-not[string]::IsNullOrEmpty($BodyAsHTML)) { $MailbodyType = 'text/HTML' $MailbodyValue = (Remove-Diacritics $BodyAsHTML) Write-Verbose "Found BodyAsHTML parameter, Type is set to text/HTML" } else { $MailbodyType = 'text/plain' $MailBodyValue = (Remove-Diacritics $Body) Write-Verbose "Found no BodyAsHTML parameter, Type is set to text/plain" } # Check for attachments. If they are present, convert to Base64 if ($AttachmentPath) { Write-Verbose "AttachmentPath parameter was used" $AllAttachments = @() foreach ($Attachment in $AttachmentPath) { try { if ($PSVersionTable.PSVersion.Major -lt 6) { $EncodedAttachment = [convert]::ToBase64String((Get-Content $Attachment -encoding byte)) } else { $AttachmentContent = Get-Content -Path $Attachment -AsByteStream -ErrorAction Stop $EncodedAttachment = [convert]::ToBase64String($AttachmentContent) } Write-Verbose "Attachment found at $Attachment has been encoded" } Catch { Throw "Could not convert file $Attachment" } # Get the extension for the attachment type $AttachmentExtension = $Attachment.Split('.')[-1] Switch ($IsWindows) { $true { $AttachmentName = $Attachment.Split('\')[-1] } $false { $AttachmentName = $Attachment.Split('/')[-1] } $Null { $AttachmentName = $Attachment.Split('\')[-1] } default { Throw "Could not work with attachmentpath" } } Write-Verbose "AttachmentExtension: $AttachmentExtension" $ImageExtensions = @("jpg", "png", "gif") if ($ImageExtensions -contains $AttachmentExtension) { $Type = "image/$AttachmentExtension" Write-Verbose "Attachment is an image, type set to $Type" } else { $Type = "Application/$AttachmentExtension" Write-Verbose "Attachment is not an image, type set to $Type" } $Attachmentobject = [pscustomObject]@{ AttachmentName = $AttachmentName EncodedAttachment = $EncodedAttachment AttachmentType = $Type } $AllAttachments += $Attachmentobject } Write-Verbose "$($AllAttachments.Count) attachments have been processed" } # Create to, cc, bcc objects if needed Write-Verbose "Adding toAddress array if needed" $ToAddresses = New-AddressArray -Addresses $ToAddress -Names $ToName Write-Verbose "Adding ccAddress array if needed" $CCAddresses = New-AddressArray -Addresses $CCAddress -Names $CCName Write-Verbose "Adding bccAddress array if needed" $BCCAddresses = New-AddressArray -Addresses $BCCAddress -Names $BCCName Write-Verbose "Creating SendGrid object" # Create a body to send to the API $Personalization = @{ 'subject' = (Remove-Diacritics $Subject) } Write-Verbose "adding subject: $($Personalization.subject)" if ($ToAddresses) { $Personalization.Add('to', @($ToAddresses)) } if ($CCAddresses) { $Personalization.Add("cc", @($CCAddresses)) } if ($BCCAddresses) { $Personalization.Add("bcc" , @($BCCAddresses)) } $SendGridBody = [pscustomObject]@{ "personalizations" = @( $Personalization ) "content" = @( @{ "type" = $mailbodyType "value" = $MailBodyValue } ) "from" = @{ "email" = (Remove-Diacritics $FromAddress) "name" = (Remove-Diacritics $FromName) } } # Add attachments to body if they are present if ($AttachmentPath) { $Attachments = @() $i = 0 foreach ($Attachmentobject in $AllAttachments) { Write-Verbose "Attachment is added to body" $Object = @{ content = $Attachmentobject.EncodedAttachment filename = $Attachmentobject.AttachmentName type = $Attachmentobject.AttachmentType disposition = $AttachmentDisposition } if ($AttachmentID) { # AttachmentIDs are added in the same order as the attachments $Object.add("content_id", $AttachmentID[$i]) } $Attachments += $Object $i++ Write-Verbose "Attachment Filename: $($Object.filename)" Write-Verbose "Attachment type: $($Object.type)" Write-Verbose "Attachment disposition: $($object.disposition)" Write-Verbose "Attachment ObjectID: $($object.content_id)" } $SendGridBody | Add-Member -MemberType NoteProperty -Name "Attachments" -Value $Attachments } $BodyJson = $SendGridBody | ConvertTo-Json -Depth 4 #Create the header $Header = @{ "authorization" = "Bearer $token" } #send the mail through Sendgrid $Parameters = @{ Method = "POST" Uri = "https://api.sendgrid.com/v3/mail/send" Headers = $Header ContentType = "application/json" Body = $BodyJson } if ($PSCmdlet.ShouldProcess( ("An email will be send from {0} to {1} with subject: {2}" -f $SendGridBody.from.email, $SendGridBody.personalizations.to.email, $SendGridBody.personalizations.subject), ("Do you want to send an email from {0} to {1} with subject: {2}?" -f $SendGridBody.from.email, $SendGridBody.personalizations.to.email, $SendGridBody.personalizations.subject), "Send email")) { Invoke-RestMethod @Parameters } #Remove the variables that were added by the function $NewVariables = Get-Variable | Where-Object { $StartVariables -notcontains $_.Name } Clear-Variable $NewVariables.Name -ErrorAction SilentlyContinue Write-Verbose "API has been called, function is done" } |