Send Email Plugin

Send e-mails through an e-mail form.

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 {Permissions}{Allow}{MailTo} in configure

Example

Send to:  

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 macro 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="foswikiSubmit" 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="foswikiInputField" 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="foswikiInputField" name="from" size="30" type="text" />
cc field	Optional	Text input field or hidden field	<input class="foswikiInputField" name="cc" size="30" type="text" />
subject field	Optional	Text input field or hidden field	<input class="foswikiInputField" name="subject" size="30" type="text" />
body field	Optional	Textarea or hidden field	<textarea class="foswikiInputField" cols="70" name="body" rows="6" style="width:100%"></textarea>
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 {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 {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 macro SENDEMAIL to write a feedback message on the page, on the position of the macro.

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=\"foswikiNotification\">$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=\"foswikiNotification\">$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%
Auto-Submitted: auto-generated

%BODY%

The tags %FROM%, %TO%, %CC%, %SUBJECT% and %BODY% are replaced with the respective form values when the email is created.

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.

Examples

Example with a handcrafted HTML form

To:

CC:

Subject:

Message:

Example with FormPlugin

This form asks for user information and validates that the fields are filled.

%STARTFORM{ name="mailForm" action="http://gsics.atmos.umd.edu/bin/sendemail/System/SendEmailPlugin" method="POST" }% This is a test%FORMELEMENT{ name="Name" type="text" mandatory="on" validate="nonempty" title="Name (First and Last):" }%%FORMELEMENT{ name="To" type="text" mandatory="on" validate="email" title="E-mail Address:" }%From: $Name Email: $Email%FORMELEMENT{ type="submit" buttonlabel="Send" }% %ENDFORM%

FAQ

How do I create linebreaks in the email body?

Use the token $n to create newlines.

How do I send data form fields?

If you have a data 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="foswikiHidden" cols="80" rows="6">
  Title: %FORMFIELD{"Title"}%
  Summary: %FORMFIELD{"Summary"}%
  </textarea>
  

Plugin test

• SendEmailPlugin is 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

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Change History

20 May 2022	2.00 Michael Daum: remove dependency on CGI for rendering html; use utf8 encoding when sending emails; support ajax-sending mail forms
09 Sep 2017	1.55 fix switchboard configuration
15 Mar 2013	1.54 Michael Daum: don't send an empty CC; fix adding css to the header
25 Aug 2011	1.53 Fixes a bug in the example form.
13 Mar 2010	1.52 Improved error feedback and documentation.
28 Feb 2010	1.51 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.42 Arthur Clemens: Added configure settings to download.
29 Mar 2009	1.41 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.
12 Mar 2009	1.3 Foswiki version.
06 Nov 2008	1.23 Michael Daum: Fixed CC emails; fixed css in docu
17 Oct 2008	1.21 Michael Daum: Added support for TWiki-5; fixed sending emails to login names
26 Jun 2008	1.20 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.13 Arthur Clemens: Fixed bug in bin script that caused form query data to get emptied.
15 may 2007	1.12 Arthur Clemens: Improved error notifications.
13 May 2007	1.11 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.