Send-KFMail

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.

Starting with kenaflow 3.0.3 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.

See the example below.

$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>]

Starting with kenaflow 3.0.3 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 (kenaflow >= 3.0.3 is required). "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

Related Cmdlets

• Invoke-KFTemplate