Send-KFMail

Syntax

Send-KFMail
  [-RedirectMailMessage <mail-message>]
  [-Body] <string>
  [-Subject] <string>
  [-To] <address>
  [-CC <address>]
  [-BCC <address>]
  [-From <address>]
  [-ReplyTo <address>]
  [-Attachments <object-or-list>]
  [-IsHTMLMail[:$true]]
  [-ThrowResolveErrors[:$false]]
  [-FloodProtectionFile <filename>]
  [-FloodProtectionTBE <time-in-seconds>]

  [-Item <item-object>]
  [-ClientContext <client-context-object>]
  [-IgnoreSharePointGroups[:$true]]
  [-IgnoreUserWithEmptyMailAddress[:$true]]
  [-ResolveSharePointGroups[:$false]]

Support

>= kenaflow 1.0.0

"LinkedResources" in Attachments are supported starting with kenaflow 2.0.33.

Return

Nothing

Description

With this cmdlet you can easily send mails.

SMTP-Server, Credentials, Port, etc. are configured in kenaflow global configuration, section "Mail".

To prevent mail flood you can specify a flood protection file that contains the timestamp of last send mail. If you specify this together with -FloodProtectionTBE mails will not be send for the specified amount of time for all Send-KFMail statements that use the same flood protection file.

Normally the parameters -To, -CC and -BCC accept strings with , or ; separated lists of email addresses or SharePoint lists with such strings, like `@("test1@example.com", "test2@example.com;test3.example.com").

-ReplyTo and -From are taken from the workflow config _wfconfig.ps1 or - if not specified there - from the global configuration of kenaflow.

If you use the cmdlet in a SharePoint workflow script you can use some additional parameters to control the behaviour. Especially the "resolving tool" for email addresses are more advanced than for the other workflows because addressees are collected from different sources. Also templates with placeholders are available for addressing

Example: -To "{{Author}};{{Editor}}" This can be used to address the creator and the last editor of the currently processed list item. The kenaflow template engine is used to resolve the strings: Templates.

The result of resolving the address strings of -To, -CC and -BCC are lists of email addresses. If there goes something wrong to determine email addresses the cmdlet will fail with an exception.

To reduce the cases of errors you can specify -IgnoreUserWithEmptyMailAddress.

SharePoint groups are also a problem because it's not possible by default to send their users a mail. You can specify -IgnoreSharePointGroups to ignore all SharePoint groups that are resolved. Or you specify -ResolveSharePointGroups to ask kenaflow to resolve SharePoint groups and use their members as recipients.

If there are exceptions they will not be thrown as long as you do not use -ThrowResolveErrors.

If the template placeholders like {{Author}} should be taken from a different list item or in a site workflow where you do not have a "currently processed" list item by default, you can use -Item to specify a list item.

You can use parameter -RedirectMailMessage in email workflows to re-send the currently processed mail. It is send by kenaflow with its SMTP settings. The <mail-message> object (as described in this article: Email Workflows) must be provided.

The following properties of the <mail-message> are used. They can be overwritten by specifying the corresponding cmdlet parameters.

  • Body
  • Subject
  • Attachments

To use the HtmlBody of the <mail-message> please specify -IsHtmlMail with the cmdlet.

If a prefix and/or suffix for email is configured for the kenaflow instance (Global Config section "Mail") this/these is/are added to the subject of the re-send email!

See the example below.

Attachments

You can attach files to the mail.

You can specify an object like this: @{FileName = "..."; <source> = <object>; ContentType = "..."; ContentId = "..."}

Since kenaflow 2.0.33 you can specify LinkedResource = $true in the attachment so configure the attachment to be a "LinkedResource", e.g. for embedded images. Please see the examples below. In this case you can omit the FileName. LinkedResources only work if -IsHTMLMail is specified.

ContentType and ContentId are optional in case of LinkedResource = $false (default if not specified) but required for "LinkedResource".

You can eigther specify one attachment object or a list of such object with @( @{...}, @{...}, ... )

Description of <source> = <object> :

<soure> can be one of this keys:

  • URL : is a server-relative Url in SharePoint. If the referenced file is in another web you can add property ClientContext to the attachment object.
  • Stream : is an open stream object
  • Base64 : is a base64 encoded string that represents the attachment.
  • Path : is a path to a file. Paths can be relative to the workflow folder.
  • Bytes : is a attachment given as Byte array.
  • Text : is a plain text.

ContentType can be specified as full MIME content type like "image/jpeg" or as one of these shortcuts:

  • PNG
  • TIFF or TIF
  • JPEG or JPG
  • PDF
  • SVG

If the shortcut is other than this the content type "application/octet-stream" will be used for "unspecified type such as binary".

Best Practice Pattern

Ideally, you define the template in the configuration list and use it directly in the mail via KFTemplate. It is also recommended to start the subject in the mail with a unique identifier for each workflow so that the user can assign it more easily.

$body = (Invoke-KFTemplate -Template $config['tpl.Mailtemplate'])

Send-KFMail -To "{{Editor}}" -CC "{{Author}}" -IsHTMLMail -Subject "Workflowname: Item with ID {{ID}} changed" -Body $body

Parameter

[-RedirectMailMessage <mail-message>]

You can re-send mails from email workflows. Please read the description above.

[-Body] <string>

The mail body.

[-Subject] <string>

The mail subject.

[-To] <address(es)>

The receiver of the mail. This string is automatically processed by the kenaflow template engine. You can specify SharePoint item fields like this: -To "{{Editor}};{{Author}}" This will send the mail to the creator and the last editor of the current SharePoint list item or of the specified list item in -Item. You can specify strings from the workflow configuration list like this: -To "[[some_config_key]]"

[-CC <address(es)>]

CC receiver. The string is processed by the kenaflow template engine. Please see description of parameter -To above.

[-BCC <address(es)>]

Bcc receiver. The string is processed by the kenaflow template engine. Please see description of parameter -To above.

[-From <address>]

This can be specified to overwrite the sender address configured in _wfconfig.ps1 OR in Global Configuration (if not overwritten by _wfconfig.ps1).

[-ReplyTo <address>]

This can be specified to overwrite the reply-to address configured in _wfconfig.ps1 OR in Global Configuration (if not overwritten by _wfconfig.ps1).

[-Attachments <object-or-list>]

Please read the section "Attachments" above.

[-IsHTMLMail[:$true]]

By default mail is send as plain text. But if you specify this switch parameter the mail is send as HTML mail. You need to specify HTML code in the -Body by yourself.

[-ThrowResolveErrors[:$false]]

By default no address resolving errors are thrown. Not resolved users/placeholders/... are ignored. The mail is only send to receipients whos email address could be resolved.

[-FloodProtectionFile <filename>]

This setting together with -FloodProtectionTBE can be used to configure flood protection. If specified the timestamp of the last mail ist stored in this file. If a relative path is used it's relative to the _wfdata folder inside the workflow folder.

[-FloodProtectionTBE <time-in-seconds>]

This setting together with -FloodProtectionFile can be used to configure flood protection. Here you specify the amout of time (in seconds) that need to elapse before a new mail will be send. This time is relative to the timestamp stored in the flood protection file.

[-Item <item-object>]

Here you can specify a different list item if you want to use the template engine for -To, -CC and -BCC with values from another list item than the current.

This setting is only available in SharePoint related workflows.

[-ClientContext <client-context-object>] [-IgnoreSharePointGroups[:$true]] [-IgnoreUserWithEmptyMailAddress[:$true]] [-ResolveSharePointGroups[:$false]]

Examples

In this example, the mail is sent to the person who created and changed an entry and the ID of the changed element is specified in the mail.

Send-KFMail -To "{{Editor}}" -CC "{{Author}}" -IsHTMLMail `
  -Subject "Something changed" -Body "ItemID: {{ID}}" `
  -From "{{Editor}}" -ReplyTo "[[user.workflowowner]]"

In the following example you see how to send a plain text string as mail attachment. The string array for the -Body is converted to a single string. This is required and the code snipped can be useful sometimes.

$lines = @()
$lines += "An email"
$lines += "from kenaflow"

Send-KFMail -To "somebody@example.com" -Subject "Mail from kenaflow" `
  -Body ([string]::Join(" ", $lines)) `
  -Attachments @( 
     @{
         FileName="PlainText.txt"; 
         Text="This is a test from kenaflow"; 
         ContentType="text/plain"
     } 
   )

In this example a mail with an embedded image as "LinkedResource" is send to the person stored in custom field "Assignee". The embedded image is stored in the workflow folder.

Send-KFMail -Subject "A mail send with kenaflow" -To "{{Assignee}}" -Body "<html><body><img src='cid:myImg'></body></html>" -Attachments @(
	@{ Path = "kenaflow.png"; ContentType="png"; ContentId = "myImg"; LinkedResource = $true}
)

In this example a mail with an embedded image as "LinkedResource" is send to the person stored in custom field "Assignee". The embedded image is stored in SharePoint.

Send-KFMail -Subject "A mail send with kenaflow" -To "{{Assignee}}" -Body "<html><body><img src='cid:myImg'></body></html>" -Attachments @(
	#server relative URL!!
	@{ URL = "/sites/kenaflow/SiteAssets/kenaflow.png"; ContentType="png"; ContentId = "myImg"; LinkedResource = $true}
)

In the following case we use a file from another site collection

$otherSiteCollectionContext = new-object Microsoft.sharepoint.client.clientcontext("https://sharepoint.farm/sites/kenaflow")

send-kfmail -subject "test" -to "ik@kenaro.com" -body "<html><body><img src='cid:myImg'></body></html>" -attachments @(
	#server relative URL!!
	@{ URL = "/sites/kenaflow/shared documents/test.png"; ContentType="png"; ContentId = "myImg"; LinkedResource = $true; ClientContext=$otherSiteCollectionContext}
)

This will redirect an email from a email workflow script. "From" (Sender) and "To" (Recipient) are taken from the cmdlet parameters. All other email properties (Subject, Body, Attachments) are taken from the processed email. HtmlBody is used from the processed email if present.

Send-KFMail -RedirectMailMessage $mail -From "kenaflow@example.com" -To "me@example.com" -IsHtmlMail

Discussion