Tags:
create new tag
view all tags

SendMailPlugin

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.

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip SendMailPlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/SendMailPlugin.txt Plugin topic
      data/Sandbox/SendMailPluginDemo.txt Demo topic
      lib/TWiki/Plugins/SendMailPlugin.pm Plugin Perl module
      lib/TWiki/Plugins/SendMailPlugin/Config.spec Plugin configuration file
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section.
    • Test if the installation was successful: See example above.

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
2016-01-19: TWikibug:Item7716: Fix for addressee with plain mail address no longer working
2016-01-14: TWikibug:Item7708: Copyright update to 2016
2015-08-18: TWikibug:Item7681: Support WikiNames in e-mail parameters
2015-01-22: TWikibug:Item7604: Switch from GPL v2 to v3; more docs on send on topic creation example
2014-10-25: TWikibug:Item7568: Doc fix in REST demo
2014-08-20: TWikibug:Item7547: Add REST interface to send mail
2013-02-10: TWikibug:Item7123: Use TWISTY in installation instructions and change history; fix issue with VarSENDMAIL include in EmailAndNotificationVariables
2012-11-14: TWikibug:Item7020: Categorize TWiki Variable SENDMAIL
2012-06-08: TWikibug:Item6885: Support HTML and MIME Multi-Part e-mail messages
2012-04-10: TWikibug:Item6867: Fix for no e-mail sent if excludetopic parameter is missing
2012-04-02: TWikibug:Item6837: Add image
2012-03-14: TWikibug:Item6860: Add configure settings; add excludetopic parameter; add VarSENDMAIL doc; adding examples
2012-03-13: TWikibug:Item6848: Initial version
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

Physics WebpagesRHUL WebpagesCampus Connect • Royal Holloway, University of London, Egham, Surrey TW20 0EX; Tel/Fax +44 (0)1784 434455/437520

Topic revision: r0 - 20 Jan 2016 - TWikiContributor

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding RHUL Physics Department TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.SendMailPlugin.