Tags:
create new tag
view all tags

Send Email Plugin

Send e-mails via a web form

Overview

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

Screenshot

Usage

  1. Create a form on the page that invokes the sendemail script
  2. Add a "to" field and a submit button
  3. Make sure to fill in allowed 'to' addresses in setting {Plugins}{SendEmailPlugin}{Permissions}{Allow}{MailTo} in configure

<form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST">
<input type="hidden" name="subject" value="hello!" />
<input type="hidden" name="body" value="howdy!" />
<input type="text" class="twikiInputField" name="to" size="30" />&nbsp;
<input type="submit" class="twikiSubmit" value="Send" />
</form>

 

Usage details

Sending emails through a form may contain these elements:

  1. An HTML form
  2. Allow/restrict settings in configure
  3. Optionally a feedback message variable SENDEMAIL
  4. Optionally a custom email template

HTML form elements

The HTML form encapsulates the data to be sent, each part passed as a form field, either an input field or hidden field.

<form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST">
... fields ...
<input type="submit" class="twikiSubmit" value="Send" />
</form>

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.

Element Required Description Example
name,method Required A form must have a name; send method is POST.  
action Required Must call sendemail script action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%"
to field Required Text input field or hidden field <input class="twikiInputField" name="to" size="30" type="text" />
from field Optional Text input field or hidden field. May be used to specify a different sender, otherwise defaults to the mail address of the current user. <input class="twikiInputField" name="from" size="30" type="text" />
cc field Optional Text input field or hidden field <input class="twikiInputField" name="cc" size="30" type="text" />
subject field Optional Text input field or hidden field <input class="twikiInputField" name="subject" size="30" type="text" />
body field Optional Textarea or hidden field <textarea class="twikiInputField" cols="70" name="body" rows="6" style="width:100%"></textarea>
html field Optional (Presumably) hidden field. If passed and is either "on" or "1", the body field value is regarded as in TWiki markup and converted into HTML. At the same time, the content-type of the email is set to text/html so that it's recognized as an HTML email. None of these happens if the field is not there or "off" is passed. <input type="hidden" name="html" value="1" />
mailtemplate field Optional (Presumably) hidden field. See Email template <input type="hidden" name="mailtemplate" value="Main.MailTemplate" />
redirectto field Optional (Presumably) hidden field. If passed, after a sent success or error, the page gets redirected to this url. <input type="hidden" name="redirectto" value="%SCRIPTURL{view}%/%WEB%/MailFeedback" />
successsection field Optional (Presumably) hidden field. Will display a named section (that you define using STARTSECTION and ENDSECTION after a successful sent. <input type="hidden" name="successsection" value="feedbackYes" />
errorsection field Optional (Presumably) hidden field. Will display a named section (that you define using STARTSECTION and ENDSECTION after an unsuccessful sent. <input type="hidden" name="errorsection" value="feedbackNo" />

Allow/restrict settings

To prevent this plugin to be used as open email relay, by default sending emails is prohibited. To send out mails, first set the mail addresses you want to allow to send to in configure. Each can be a list of comma separated regular expressions that emails are checked against before allowing the mail to be sent.

  • {Plugins}{SendEmailPlugin}{Permissions}{Allow}{MailTo} - enter .* to allow to send to anyone
  • {Plugins}{SendEmailPlugin}{Permissions}{Deny}{MailTo}

Other preferences can be set depending on your needs:

  • {Plugins}{SendEmailPlugin}{Permissions}{Allow}{MailFrom}
  • {Plugins}{SendEmailPlugin}{Permissions}{Deny}{MailFrom}
  • {Plugins}{SendEmailPlugin}{Permissions}{Allow}{MailCc}
  • {Plugins}{SendEmailPlugin}{Permissions}{Deny}{MailCc}

Each Deny is evaluated after each Allow, so Deny settings overrule Allow settings.

Examples of allow/restrict settings

  • Allow to send to:
    • Set {Plugins}{SendEmailPlugin}{Permissions}{Allow}{MailTo} to:
      • john@tar.com to only allow to send mails to John
      • john@tar.com|mary@look.ca to allow to send mails to John and Mary
      • .*@tar.com to send mails to any address at @tar.com
      • .*@tar.com,mary@.* to send mails to any address at @tar.com and to all Marys in the world
  • Deny to send to:
    • Set {Plugins}{SendEmailPlugin}{Permissions}{Deny}{MailTo} to:
      • .*@tar.com to deny to any address at @tar.com
      • .* to deny any address (no emails will be sent)

The same rules apply for {MailFrom} and {MailCc}.

Feedback notifications

Use the variable SENDEMAIL to write a feedback message on the page, on the position of the variable.

Simply:

%SENDEMAIL%
will write a feedback message (if any), using the default message strings set in configure.

The message can be tailored using SENDEMAIL parameters:

Parameter Description Example
feedbackSuccess Message string in case of successful send. feedbackSuccess="Request sent, we'll contact you shortly."
feedbackError Message string in case of unsuccessful send. feedbackError="Could not send your message, please contact us."
format A format string. Use $message as placeholder for the actual feedback message. format="<div class=\"twikiNotification\">$message</div>"

Feedback notification example

%SENDEMAIL{
feedbackSuccess="Request sent, we'll contact you shortly."
feedbackError="Could not send your message, please contact us."
format="<div class=\"twikiNotification\">$message</div>"
}%

Email template

To customize the email, including its header, create a new template topic and pass the topic name in a mailtemplate form field. The default template is SendEmailPluginTemplate:
From: %FROM%
To: %TO%
CC: %CC%
Subject: %SUBJECT%
MIME-Version: 1.0
Content-Type: %CONTENT_TYPE%; charset=%CHARSET%
Content-Transfer-Encoding: 8bit

%BODY%
The tags %FROM%, %TO%, %CC%, %SUBJECT% and %BODY% are replaced with the respective form field values when the email is composed. %CONTENT_TYPE% is replaced with either text/plain or text/html depending on the html form field value. %CHARSET% is replaced with the charset of this site.

For a template topic named MailTemplate you can either pass the name Mail or MailTemplate.

The search path for templates always starts in the current web.

Miscellaneous config

Config Description Default Current
value
$TWiki::cfg{Plugins}{SendEmailPlugin}{Debug} Enable debugging (debug messages will be written to TWiki debug log file) 0 0
$TWiki::cfg{Plugins}{SendEmailPlugin}{AlwaysFromTheUser} User can't change the "from" field when sending email. It's always the email adress of current user. 0 0
$TWiki::cfg{Plugins}{SendEmailPlugin}{Retry} Setup the retrying times when sending email. 1 1
$TWiki::cfg{Plugins}{SendEmailPlugin}{ExpandVariablesInTemplate} Expand variables in an email template. Depending on this value, the default template is either SendEmailPluginTemplate or SendEmailPluginExpandedTemplate. If you compare the two templates, you see the placeholders for the recipients, subject, etc. are different. The reason why SendEmailPluginExpandedTemplate's placeholders have the SENDEMAIL_ prefix is to avoid conflicts with other variables. If variables in a template is not expaneded, there is no need to worry about conflicts between placeholders and variables, hence placeholders are shorter. 0 0

Examples

Example with a handcrafted HTML form

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

The following form is disabled because only the first SendEmailPlugin form on a topic works. This is the second.

Send Email

To:

CC:

Subject:

Message:

%SENDEMAIL%

Example with FormPlugin

This form asks for user information and validates that the password confirmation matches the password.

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

The following form is disabled because only the first SendEmailPlugin form on a topic works. This is the third.

Send Email * All fields are required.

Name (First and Last):
*

E-mail Address:
*

Password (caps sensitive):
*

Confirm your password:
*

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

FAQ

How do I send data form fields?

If you have a TWiki 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:
    <input type="hidden" name="body" value="Title: %FORMFIELD{"Title"}%, Summary: %FORMFIELD{"Summary"}%" />
    
  • preserve linebreaks by putting them in a textarea:
    <textarea name="body" class="twikiHidden" cols="80" rows="6">
    Title: %FORMFIELD{"Title"}%
    Summary: %FORMFIELD{"Summary"}%
    </textarea>
    

Plugin test

  • SendEmailPlugin is not enabled.

Plugin Settings

  • Plugin settings are set in configure.
  • Note: by default any emailing is prohibited. Change the settings in configure to set to which addresses you allow mails to be sent from and to.

CSS classes

HTML elements with these style names are written to the default feedback.
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 extension. The following instructions are for the administrator who installs the extension 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 extension home on twiki.org (see below).
    • Unzip SendEmailPlugin.zip in your twiki installation directory.
    • 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 if needed.
    • Test if the installation was successful using the examples provided.

Plugin Info

Plugin Author: TWiki:Main.ArthurClemens
Copyright: © 2007-2010 Arthur Clemens; 2008 Michael Daum
© 2007-2013 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2013-05-28
Change History:  
2013-05-28: Twikubg:Item7268: HTML email support
2013-04-24: TWikibug:Item7239: Shortcomings in template handling and documentation are fixed
2013-04-23: TWikibug:Item7237: Config parameter inconsistency fix
2013-01-24: TWikibug:Item7129: TWiki.SendEmailPlugin 2nd and 3rd email forms are bound to fail
2013-01-24: TWikibug:Item7045: Make SendEmailPlugin hiding URL "get" parameters when rediecting to a target page.
2012-11-21: TWikibug:Item7048: Block the "from" field for security purpose.
2012-11-21: TWikibug:Item7047: Configure retry times in config file.
2012-11-21: TWikibug:Item7046: SendEmailPlugin doesn't expand variables in an email template
2011-04-02: TWikibug:Item6676: Plugin update 2010 from related project and doc improvements
28 Feb 2010 1.5.1 Added forgotten Config.spec file.
08 Jan 2010 1.5 Arthur Clemens: Improved error feedback; added format parameter; moved the mail template to a topic; changed param template to mailtemplate.
03 Jan 2010 1.4.2 Arthur Clemens: Added configure settings to download.
29 Mar 2009 1.4.1 Arthur Clemens: Removed default restrictions in Deny settings so that only the Allow setting needs to be set to send emails.
21 Mar 2009 1.4 Arthur Clemens: Moved topic and hardcoded settings to configure.
06 Nov 2008 1.2.3 Michael Daum: Fixed CC emails; fixed css in docu
17 Oct 2008 1.2.1 Michael Daum: Added support for TWiki-5; fixed sending emails to login names
26 Jun 2008 1.2.0 Michael Daum: 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 Arthur Clemens: Fixed bug in bin script that caused form query data to get emptied.
15 may 2007 1.1.2 Arthur Clemens: Improved error notifications.
13 May 2007 1.1.1 Arthur Clemens: 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: 4.2 or later
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/SendEmailPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/SendEmailPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/SendEmailPluginAppraisal

Related Topics: SendEmailPluginTemplate, SendEmailPluginExpandedTemplate, AdminDocumentationCategory, TWikiPreferences, TWikiPlugins

Topic revision: r0 - 2013-04-23 - 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 TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.SendEmailPlugin.