(r1) SendMailPlugin < TWiki

TWiki Web>SendMailPlugin (revision 1) (raw view)
---+!! !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.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Introduction

<sticky><div style="float:right; padding: 0 10px 0 10px;">
<img src="%ATTACHURLPATH%/email-workflow-200.png" alt="" width="200" height="113" />
</div></sticky>
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 Sandbox.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.

#SyntaxRules
---++ Syntax Rules

=%<nop>SENDMAIL{ action="send" ... }%=

%INCLUDE{ "VarSENDMAIL" section="parameters" }%

#RestInterface
---++ REST Interface

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

Example REST call: %BR%
=%SCRIPTURL{rest}%/SendMailPlugin/sendmail?action=send;to=tom@example.com;subject=Hi+there;text=This+is+Jane.=

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

#OpenMailRelay
---++ 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 =%<nop>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:

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

---+++ 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:

<verbatim>
%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" }%
</verbatim>

__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 %SYSTEMWEB%.TWikiTemplates#DefaultVariableExpansion describes URLPARAM for topic text.
   * TWiki expands only the [[%SYSTEMWEB%.TWikiTemplates#DefaultVariableExpansion][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 Sandbox.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:

<verbatim>
%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%
</verbatim>

---+++ Send E-mail from !JavaScript Code

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

---++ Plugin Installation &amp; 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.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][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 ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
        | ==data/Sandbox/SendMailPluginDemo.txt== | Demo topic |
        | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/%TOPIC%/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 [[%SCRIPTURL{configure}%][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.
%ENDTWISTY%

---++ Plugin Info

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

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2012 Hypertek lnc. <br /> &copy; 2012-2016 TWiki:Main.PeterThoeny <br /> &copy; 2012-2016 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]], Hypertek lnc. and NIST |
|  Plugin Version: | 2016-01-19 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  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 |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins.Benchmark: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% 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, Sandbox.SendMailPluginDemo, Sandbox.SendMailPluginRestDemo, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences
Topic revision: r1 - 22 Jan 2019 - TWikiAdminUser
Account
- Log In
- Register User
~~Edit~~
~~Attach~~
Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.SendMailPlugin.