Send Email Plugin

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

Usage

• Create a form on the page.
  • Call action script sendemail
    • action="%SCRIPTURL{sendemail}%/%WEB%/%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 %SENDEMAIL% anywhere on the page where the feedback should appear.
  • Optionally pass parameters feedbackSuccess and feedbackError. Default feedback messages are set below in 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:

  From: %FROM%
  To: %TO%
  CC: %CC%
  Subject: %SUBJECT%
  
  %BODY%

  The tags %FROM%, %TO%, %CC%, %SUBJECT% and %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 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 support, use the following settings

  * Set ALLOWMAILTO = support
  * Set DENYMAILTO =
  * Set DENYMAILFROM = 

• 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

Show code Hide code

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

-->

Example with FormPlugin

Show code Hide code

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

%STARTFORM{ name="mailForm" action="http://twiki.ufba.br/twiki/bin/sendemail/TWiki/SendEmailPlugin" method="POST" onSubmit="return checkPasswords(this)" }%

FAQ

How do I send form fields?

• 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 Tests

• SendEmailPlugin is enabled.

Plugin Settings

• One line description, is shown in the 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

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 SendEmailPlugin.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:

  $TWiki::cfg{SwitchBoard}{sendemail} = ['TWiki::Plugins::SendEmailPlugin::Core', 'sendEmail', {sendemail => 1}];

  and redirect all calls to sendemail to sendemail-5 in your apache configuration.

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins