>
> | SendMailPlugin
<--
Contributions to this plugin are appreciated. Please update the plugin page at
http://twiki.org/cgi-bin/view/Plugins/SendMailPlugin or provide feedback at
http://twiki.org/cgi-bin/view/Plugins/SendMailPluginDev.
If you are a TWiki contributor please update the plugin in the SVN repository.
-->
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.
<--/twistyPlugin twikiMakeVisibleInline-->
- 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.
<--/twistyPlugin-->
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
<--/twistyPlugin twikiMakeVisibleInline--> <--/twistyPlugin-->
Related Topics: VarSENDMAIL, SendMailPluginDemo, SendMailPluginRestDemo, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences
| META FILEATTACHMENT |
attachment="email-workflow-400.png" attr="h" comment="" date="1333351305" name="email-workflow-400.png" path="email-workflow-400.png" size="59125" user="TWikiContributor" version="1" |
| META FILEATTACHMENT |
attachment="email-workflow-200.png" attr="h" comment="" date="1333351305" name="email-workflow-200.png" path="email-workflow-200.png" size="19594" user="TWikiContributor" version="1" |
|
Copyright © 1999-2023 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.