SendEmailPlugin < TWiki/

---+!! Send Email Plugin

*Allows to send e-mail through an e-mail form.*

%TOC%

---++ Usage

   * Create a form on the page.
      * Call =action= script =sendemail=
         * =action="%<nop>SCRIPTURL{sendemail}%/%<nop>WEB%/%<nop>TOPIC%"=
      * Required is a field with =name="to"=
      * Optional are the fields =cc=, =subject=, =body=, =template=,  =redirectto=, =successsection= and =errorsection=
      * The =from= field may be used but defaults to the address of the current user.
   * To show feedback write =%<nop>SENDEMAIL%= anywhere on the page where the feedback should appear.
      * Optionally pass parameters =feedbackSuccess= and =feedbackError=. 
        Default feedback messages are set below in [[#PluginSettings][Plugin Settings]].
   * The =redirectto= is an url to redirect to a different landing page after the mail has been sent.
   * The =successsection= parameter optionally sets the named section to be extracted.
   * The =errorsection= parameter specifies the named section to be extracted when an error occured.
   * To customize the email, including its header, create a new template file (or topic) and set the
     =template= parameter to it. The default template is stored in the =sendemail.tmpl= file:
     <verbatim>
From: %FROM%
To: %TO%
CC: %CC%
Subject: %SUBJECT%

%BODY%</verbatim>
      The tags =%<nop>FROM%=, =%<nop>TO%=, =%<nop>CC%=, =%<nop>SUBJECT%= and =%<nop>BODY%= are replaced
      with the respective url parameter when the email is created.
   * The value of the recipient's and sender's email address can be restricted using the
     preference variables: 
     =ALLOWMAILTO=,
     =DENYMAILTO=,
     =ALLOWMAILFROM=,
     =DENYMAILFROM=,
     =ALLOWMAILCC= and 
     =DENYMAILCC=. 
     Each can be a list of comma separated regular expressions that emails are checked against before
     allowing the mail to be send. This is needed to prevent this plugin from being used as an open email relay
     and potentially being missused to create spam emails. By default, this plugin will prohibit any email to be send.
     You will have to change the settings [[#PluginSettings][below]] to match your needs. Preferably,
     keep the settings as they are as a security measure and enable sending emails on a per-form basis
     by setting the respective topic preferences in the topic holding the send-email form. For example, to
     allow the email form on the current topic to be send to the <nop>support, use the following settings
     <verbatim>
* Set ALLOWMAILTO = support
* Set DENYMAILTO =
* Set DENYMAILFROM = </verbatim>
   * Note, that the =From=, =To= and =CC= parameters can be either an email address or a wiki user name,
     in which case the email address of that wiki user is used instead.

---++ Example
%TWISTY{showlink=" Show code" hidelink=" Hide code" showimgleft="%ICONURLPATH{toggleopen}%" hideimgleft="%ICONURLPATH{toggleclose}%" mode="div"}%
<verbatim>
<form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST">
<input type="hidden" name="successsection" value="thanks" />
<fieldset>
<legend><b>Send Email</b></legend>
<div class="twikiFormSteps">
<div class="twikiFormStep">
<h3>To:</h3>
<input class="twikiInputField" id="to" name="to" size="30" type="text" value="%URLPARAM{"to"}%" />
</div>
<div class="twikiFormStep">
<h3>CC:</h3>
<input type="text" class="twikiInputField" id="cc" name="cc" size="30"  value="%URLPARAM{"cc"}%" />
</div>
<div class="twikiFormStep">
<h3>Subject:</h3>
<input type="text" class="twikiInputField" id="subject" name="subject" size="70" value="%URLPARAM{"subject"}%" />
</div>
<div class="twikiFormStep">
<h3>Message:</h3>
<textarea class="twikiInputField" cols="70" name="body" rows="6" style="width:100%">%URLPARAM{"body"}%</textarea>
</div>
<div class="twikiFormStep">
<input type="submit" class="twikiSubmit" value="Send" />
</div>
</div>
</fieldset>
</form>
%SENDEMAIL%
<!--
%STARTSECTION{"thanks"}%
---+ Notification
%SENDEMAIL%
<input type="button" value="Ok" class="twikiButton" onclick="window.location.href='%URLPARAM{"origurl" default="%SCRIPTURLPATH{view}%/%BASEWEB%/%BASETOPIC%"}%'" />
%ENDSECTION{"thanks"}%

-->
</verbatim>
%ENDTWISTY%


<form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST">
<input type="hidden" name="successsection" value="thanks" />
<fieldset style="border:1px solid #ddd; padding:1em">
<legend><b>Send Email</b></legend>
<div class="twikiFormSteps">
<div class="twikiFormStep">
---+++!! To:
<input class="twikiInputField" id="to" name="to" size="30" type="text" value="%URLPARAM{"to"}%" />
</div>
<div class="twikiFormStep">
---+++!! CC:
<input type="text" class="twikiInputField" id="cc" name="cc" size="30"  value="%URLPARAM{"cc"}%" />
</div>
<div class="twikiFormStep">
---+++!! Subject:
<input type="text" class="twikiInputField" id="subject" name="subject" size="70" value="%URLPARAM{"subject"}%" />
</div>
<div class="twikiFormStep">
---+++!! Message:
<textarea class="twikiInputField" cols="70" name="body" rows="6" style="width:100%">%URLPARAM{"body"}%</textarea>
</div>
<div class="twikiFormStep">
<input type="submit" class="twikiSubmit" value="Send" />
</div>
</div>
</fieldset>
</form>
%SENDEMAIL%

<!--
%STARTSECTION{"thanks"}%
---+ Notification
%SENDEMAIL%
<input type="button" value="Ok" class="twikiButton" onclick="window.location.href='%URLPARAM{"origurl" default="%SCRIPTURLPATH{view}%/%BASEWEB%/%BASETOPIC%"}%'" />
%ENDSECTION{"thanks"}%
-->

---+++ Example with <nop>FormPlugin
This form asks for user information and validates that the password confirmation matches the password.

%TWISTY{showlink=" Show code" hidelink=" Hide code" showimgleft="%ICONURLPATH{toggleopen}%" hideimgleft="%ICONURLPATH{toggleclose}%" mode="div"}%
<verbatim>
%STARTFORM{
name="mailForm"
action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%"
method="POST"
onSubmit="return checkPasswords(this)"
}%
<fieldset style="border:1px solid #ddd; padding:1em">
<legend><b>Send Email</b></legend>
%RED%*%ENDCOLOR% All fields are required.
%FORMELEMENT{
name="To"
type="hidden"
title="To:"
default="me@myurl.com"
}%
%FORMELEMENT{
name="Subject"
type="hidden"
default="Account Request"
}%
%FORMELEMENT{
name="Name"
type="text"
mandatory="on"
title="Name (First and Last):"
}%
%FORMELEMENT{
name="Email"
type="text"
mandatory="on"
validate="email"
title="E-mail Address:"
}%
%FORMELEMENT{
name="Password"
type="password"
mandatory="on"
title="Password (caps sensitive):"
}%
%FORMELEMENT{
name="Confirm"
type="password"
mandatory="on"
title="Confirm your password:"
}%
%FORMELEMENT{
name="body"
type="textarea"
rows="10"
cols="80"
cssclass="twikiHidden"
default="$Name
$Email
$Company
$Password
$Confirm"
}%
%FORMELEMENT{
type="submit"
buttonlabel="Send"
}%
</fieldset>
%ENDFORM%

%SENDEMAIL{feedbackSuccess="Request sent, we'll contact you shortly." feedbackError="Could not send your message, please contact us." }%

<script type="text/javascript">
//<![CDATA[
function checkPasswords(inForm) {
	if(inForm.Password.value != inForm.Confirm.value) {
		alert('Your passwords do not match. Please try again.');
		return false;
	}
	return true;
}
//]]>
</script>
</verbatim>
%ENDTWISTY%

%STARTFORM{
name="mailForm"
action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%"
method="POST"
onSubmit="return checkPasswords(this)"
}%
<fieldset style="border:1px solid #ddd; padding:1em">
<legend><b>Send Email</b></legend>
%RED%*%ENDCOLOR% All fields are required.
%FORMELEMENT{
name="To"
type="hidden"
title="To:"
default="me@myurl.com"
}%
%FORMELEMENT{
name="Subject"
type="hidden"
default="Account Request"
}%
%FORMELEMENT{
name="Name"
type="text"
mandatory="on"
title="Name (First and Last):"
}%
%FORMELEMENT{
name="Email"
type="text"
mandatory="on"
validate="email"
title="E-mail Address:"
}%
%FORMELEMENT{
name="Password"
type="password"
mandatory="on"
title="Password (caps sensitive):"
}%
%FORMELEMENT{
name="Confirm"
type="password"
mandatory="on"
title="Confirm your password:"
}%
%FORMELEMENT{
name="body"
type="textarea"
rows="10"
cols="80"
cssclass="twikiHidden"
default="$Name
$Email
$Company
$Password
$Confirm"
}%
%FORMELEMENT{
type="submit"
buttonlabel="Send"
}%
</fieldset>
%ENDFORM%

%SENDEMAIL{feedbackSuccess="Request sent, we'll contact you shortly." feedbackError="Could not send your message, please contact us." }%

<script type="text/javascript">
//<![CDATA[
function checkPasswords(inForm) {
	if(inForm.Password.value != inForm.Confirm.value) {
		alert('Your passwords do not match. Please try again.');
		return false;
	}
	return true;
}
//]]>
</script>

---++ FAQ
---+++ How do I send form fields?
If you have a form with the fields =Title= and =Summary= and want to post the values of these fields in the body of the e-mail, eiter:
   * put them in a hidden field:
   <verbatim>
<input type="hidden" name="body" value="Title: %FORMFIELD{"Title"}%, Summary: %FORMFIELD{"Summary"}%" />
</verbatim>
   * preserve linebreaks by putting them in a textarea:
   <verbatim>
<textarea name="body" class="twikiHidden" cols="80" rows="6">
Title: %FORMFIELD{"Title"}%
Summary: %FORMFIELD{"Summary"}%
</textarea>
</verbatim>

#PluginTest
---++ Plugin Tests
   * !SendEmailPlugin is %IF{"context SendEmailPluginEnabled" then='%GREEN%enabled%ENDCOLOR%' else='%RED%not enabled%ENDCOLOR%'}%.


#PluginSettings
---++ Plugin Settings

   * One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Allows to send e-mail through an e-mail form

   * Default feedback messages:
      * Set EMAIL_SENT_SUCCESS_MESSAGE = Enviada com sucesso!
      * Set EMAIL_SENT_ERROR_MESSAGE = Mensagem não enviada.

   * Default mail permissions, (note: by default any emailing is prohibited)
      * Set ALLOWMAILTO = .*
      * Set DENYMAILTO = 
      * Set ALLOWMAILFROM = .*
      * Set DENYMAILFROM = 
      * Set ALLOWMAILCC = .*
      * Set DENYMAILCC = 

   * Debug plugin: (See output in =data/debug.txt=)
      * Set DEBUG = 0


---++ CSS classes

| *Class name* | *Note* |
| =sendEmailPluginNotification=  | Used for feedback after sending a mail  |
| =sendEmailPluginError=         | Styles =sendEmailPluginNotification= in case of an error   |



---++ Plugin Installation Instructions

__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 server where TWiki is running. 

   * Download the ZIP file from the Plugin web (see below)
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
   | ==bin/sendemail== | CGI script for TWiki 4 |
   | ==bin/sendemail-5== | CGI script for TWiki 5 |
   | ==templates/sendemail.tmpl== | Email template |
   | ==data/TWiki/SendEmailPlugin.txt== | Documentation |
   | ==lib/TWiki/Plugins/SendEmailPlugin.pm== | Plugin stub |
   | ==lib/TWiki/Plugins/SendEmailPlugin/Core.pm== | Plugin core |
   | ==pub/TWiki/SendEmailPlugin/sendemailplugin.css== | CSS styles |


   * If you install this plugin on a TWiki-5 engine you will need to add the following lines
     to your =LocalSite.cfg=:
     <verbatim>$TWiki::cfg{SwitchBoard}{sendemail} = ['TWiki::Plugins::SendEmailPlugin::Core', 'sendEmail', {sendemail => 1}];</verbatim>
     and redirect all calls to =sendemail= to =sendemail-5= in your apache configuration.

---++ Plugin Info

|  Plugin Author: | TWiki:Main.ArthurClemens |
|  Copyright: | &copy; 2007 Arthur Clemens; 2008 Michael Daum |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 1.2.2, 17 Oct 2008  |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  17 Oct 2008 | 1.2.1 TWiki:Main/MichaelDaum: added support for TWiki-5; fixed sending emails to login names |
|  26 Jun 2008 | 1.2.0 TWiki:Main/MichaelDaum: \
                 added ALLOW/DENY preference settings to prevent this plugin from being used as an open spam relay; \
                 added =template= option allowing more control over email header etc; \
                 fixed mod_perl/perperl coding errors;\
                 sender address is the current user, it will default to the wikimaster's only as a last resort; \
                 allow user names in addition to plain email addresses in From, To and Cc; \
                 allow multiple users in To and Cc; \
                 added a =redirectto=, =successsection= and =errorsection= options to land on a different feedback page; \
                 reorganized code for lazy compilation |
|  16 may 2007 | 1.1.3 TWiki:Main/ArthurClemens: fixed bug in bin script that caused form query data to get emptied. |
|  15 may 2007 | 1.1.2 TWiki:Main/ArthurClemens: improved error notifications. |
|  13 May 2007 | 1.1.1 TWiki:Main/ArthurClemens: changed sendmail script invocation to be called through bin script =sendemail=; added CSS styles for feedback notification; fixed typo 'feedbackSucces'. |
|  05 May 2007 | 1.0 First release. |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.1 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %TWIKIWEB%.GoodStyle nn%, %TWIKIWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins
This topic: TWiki/ > SendEmailPlugin
Topic revision: r2 - 01 Sep 2010 - 14:24:02 - DeniseBandeira?
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback