SendMailPlugin

Page contents

• Introduction
• Syntax Rules
• REST Interface
• Security Note on Open Mail Relay
• Examples
  • Send E-mail on Topic View
  • Send E-mail on Topic Creation
  • Send E-mail from CommentPlugin Form
  • Send E-mail from JavaScript Code
• Plugin Installation & Configuration
• Plugin Info

Send e-mail from actions in TWiki topics, useful for workflow automation

Introduction

In some TWiki applications there is a need to send e-mails as part of the workflow. This plugin is a flexible solution to send e-mails when certain actions occure, such as when submitting a form or when creating a topic. The SendMailPluginDemo is a working example showing how to send an e-mail when a user submits a form to vote on his/her favorite city.

The related TWiki:Plugins.SendEmailPlugin is a web form mailer, used for things like "contact us" web forms.

Syntax Rules

%SENDMAIL{ action="send" ... }%

Parameter	Description	Default
action=""	Only action="send" is supported, it will send an e-mail	"" (no action)
excludetopic="MyTemplate"	Exclude action for named topic. Typically used in a template topic containing the SENDMAL variable to disable the action when viewing the topic.	"" (no exclude)
from="admin@example.com"	E-mail address or WikiName of sender. If a WikiName is specified, the registered e-mail of that person is used. Supported tokens: • $webmastername - name of TWiki administrator. • $webmasteremail - e-mail of TWiki administrator. • $username - WikiName of logged in user. • $useremail - e-mail address of the logged in user. Defaults to TWiki administrator. See note on open mail relay.	"$webmastername <$webmasteremail>"
to="jom@example.com"	To list: Comma-space delimited list of e-mail addresses or WikiNames of adressees. Same tokens supported as in from="". Defaults to TWiki administrator.	"$webmastername <$webmasteremail>"
cc="jimmy@example.com"	CC list: Comma-space delimited list of e-mails or WikiNames. Same tokens supported as in from="".	""
bcc="boss@example.com"	BCC list: Comma-space delimited list of e-mails or WikiNames. Same tokens supported as in from="".	""
subject="Any text"	E-mail subject. Text may include TWikiVariables such as %URLPARAM{subject}%, and format tokens such as $n and $percnt.	(help message)
text="Any text" or plaintext="Any text"	E-mail body in plain text format. Text may include TWikiVariables and format tokens.	(help message)
htmltext="Any HTML"	E-mail body in HTML format, optional. Text may include TWikiVariables and format tokens. Double quotes need to be escaped, such as <a href=\"http://twiki.org/\">TWiki.org<a>. A MIME Multi-Part message is sent if both, plaintext and htmltext are specified.	""
onsuccess="..."	Text shown in place of the SENDMAIL variable on success, default is empty. Text may include TWikiVariables and format tokens.	""
onerror="| $error ||"	Error message shown in place of the SENDMAIL variable on error, if any. Text may include TWikiVariables and format tokens. Token $error expands to the error message.	"$error"

REST Interface

The plugin handles a sendmail REST (Representational state transfer) call. All %SENDMAIL{ }% parameters are supported, the action=send parameter is required. On error, a string is returned starting with "ERROR:".

Example REST call:
https://twiki.ph.rhul.ac.uk/twiki/bin/rest/SendMailPlugin/sendmail?action=send;to=tom@example.com;subject=Hi+there;text=This+is+Jane.

See SendMailPluginRestDemo for a working demo using a jQuery Ajax call to send an e-mail.

Security Note on Open Mail Relay

Public TWiki sites can potentially be abused as an open mail relay if this plugin is installed and enabled. The plugin can be secured as follows on public sites:

• Set the {Plugins}{SendMailPlugin}{From} configure setting to a token such as $webmasteremail, or to a fixed addess.
• Set the {Plugins}{SendMailPlugin}{To} configure setting to a token such as $useremail, or to a fixed addess.
• Set the {Plugins}{SendMailPlugin}{CC} configure setting to disable (to disable), a token such as $useremail, or to a fixed addess.
• Set the {Plugins}{SendMailPlugin}{BCC} configure setting to disable, a token, or to a fixed addess.

Setting these configure settings will disable the four corresponding %SENDMAIL{"..."}% parameters. That is, TWiki cannot be abused as an open mail relay.

Examples

This plugin has many use cases. Here are a few for inspiration.

Send E-mail on Topic View

An e-mail is sent on each topic view if the SENDMAIL variable is used in a TWiki topic with action="send". This can be very noisy. Here is an example where an e-mail is sent only if user JimmyNeutron views the topic:

%SENDMAIL{
 action="%IF{ "'%WIKINAME%'='JimmyNeutron'" then="send"}%"
 subject="%TOPIC% Topic View, conditional"
 to="$webmasteremail"
 text="Viewed by %WIKINAME%"
}%

Send E-mail on Topic Creation

It is possible to send an e-mail each time a topic is created. This example sends an e-mail when a user edits a new topic based on WebTopicEditTemplate that has the following content:

%STARTSECTION{ type="expandvariables" }%%SENDMAIL{
 action="send"
 excludetopic="WebTopicEditTemplate"
 to="$webmasteremail"
 subject="Create new topic %TOPIC%"
 text="User %WIKINAME% is editing new topic %WEB%.%TOPIC%, %SCRIPTURL{"view"}%/%WEB%/%TOPIC%
   * Title: %URLPARAM{"Title"}%
   * Description: %URLPARAM{"Description"}%"
}%%ENDSECTION{ type="expandvariables" }%

Notes:

• Keep in mind that the e-mail is sent when the user clicks on edit, not on save.
• The excludetopic="WebTopicEditTemplate" prevents the e-mail action on topic view.
• URLPARAM variables can be used in the text="..." to specify content supplied in URL parameters - the same way as TWikiTemplates#DefaultVariableExpansion describes URLPARAM for topic text.
• TWiki expands only the default variables on topic creation. In order to have the SENDMAIL variable take action we can force it to expand by placing the variable in a section of type="expandvariables" as shown.

Send E-mail from CommentPlugin Form

The CommentPlugin can be used to create custom forms and form actions. The SendMailPluginDemo is a working example showing how to send an e-mail when a user submits a form to vote on his/her favorite city.

For reference, the CommentPlugin output template looks as follows:

%TMPL:DEF{OUTPUT:vote_mail_comment}%%POS:BEFORE%| %URLPARAM{ "vote" encode="safe" }% | %WIKIUSERNAME% | %SERVERTIME% |
%STARTSECTION{ type="expandvariables" }%%SENDMAIL{
 action="%URLPARAM{sendmailaction}%"
 from="$webmastername <$webmasteremail>"
 to="$username <$useremail>"
 cc="%WIKIWEBMASTER%"
 subject="Your vote on %WIKITOOLNAME%"
 text="Dear %WIKINAME%,

Thank you for your vote!
  * You selected: %URLPARAM{ "vote" encode="safe" }%

Best regards,
TWiki administrator team"
 onerror="| $error |||$n"
}%%ENDSECTION{ type="expandvariables" }%%TMPL:END%

Send E-mail from JavaScript Code

E-mail can be sent dynamically from the browser with a REST call using some jQuery code. See REST Interface documentation above, and see working example at SendMailPluginRestDemo.

Plugin Installation & Configuration

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

Plugin Info

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Send e-mail from actions in TWiki topics, useful for workflow automation

Plugin Author:	TWiki:Main.PeterThoeny
Copyright:	© 2012 Hypertek lnc. © 2012-2016 TWiki:Main.PeterThoeny © 2012-2016 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Sponsor:	Wave Systems Corp., Hypertek lnc. and NIST
Plugin Version:	2016-01-19

TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	none
Other Dependencies:	none
Perl Version:	5.005
TWiki:Plugins.Benchmark:	GoodStyle nn%, FormattedSearch nn%, SendMailPlugin nn%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/SendMailPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/SendMailPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/SendMailPluginAppraisal

Related Topics: VarSENDMAIL, SendMailPluginDemo, SendMailPluginRestDemo, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences