You are here:
Foswiki
>
System Web
>
SendEmailPlugin
(08 Jan 2010,
ProjectContributor
)
(raw view)
E
dit
A
ttach
---+!! Send Email Plugin Send e-mails through an e-mail form. <img src="%PUBURLPATH%/%WEB%/%TOPIC%/screenshot.png" alt="Screenshot" width='797' height='378' /> %TOC% ---++ Usage 1 Create a form on the page that invokes the =sendemail= script 1 Add a "to" field and a submit button 1 Make sure to fill in allowed 'to' addresses in setting ={Permissions}{Allow}{MailTo}= in [[%SCRIPTURLPATH{configure}%#SendEmailPlugin$Extensions][configure]] ---+++ Example <form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST"> <input type="hidden" name="subject" value="hello!" /> Send to: <input class="foswikiInputField" name="to" size="30" type="text" value="email address..." /> <input type="submit" class="foswikiSubmit" value="Send" /> </form> %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="subject" value="hello!" /> Send to: <input class="foswikiInputField" name="to" size="30" type="text" value="email address..." /> <input type="submit" class="foswikiSubmit" value="Send" /> </form> </verbatim> %ENDTWISTY% ---++ Usage details Sending emails through a form may contain these elements: 1 An HTML form 1 Allow/restrict settings in configure 1 Optionally a feedback message macro =SENDEMAIL= 1 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. <verbatim> <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> </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. %TABLE{tablewidth="100%" columnwidths="15%,5%,25%,55%" sort="off" headerbg="#f5f5f5" databg="#ffffff" headercolor="#333333"}% | *Element* | *Required* | *Description* | *Example* | | =name,method= | Required | A form must have a name; send method is POST. | | | =action= | Required | Must call =sendemail= script | =action="%<nop>SCRIPTURL{sendemail}%/%<nop>WEB%/%<nop>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 [[%TOPIC%#EmailTemplate][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="%<nop>SCRIPTURL{view}%/%<nop>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 [[%SCRIPTURLPATH{configure}%#SendEmailPlugin$Extensions][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: <verbatim> %SENDEMAIL% </verbatim> will write a feedback message (if any), using the default message strings set in [[%SCRIPTURLPATH{configure}%#SendEmailPlugin$Extensions][configure]]. The message can be tailored using SENDEMAIL parameters: %TABLE{tablewidth="100%" columnwidths="15%,35%,55%" sort="off" headerbg="#f5f5f5" databg="#ffffff" headercolor="#333333"}% | *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 <verbatim> %SENDEMAIL{ feedbackSuccess="Request sent, we'll contact you shortly." feedbackError="Could not send your message, please contact us." format="<div class=\"foswikiNotification\">$message</div>" }% </verbatim> #EmailTemplate ---+++ 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 System.SendEmailPluginTemplate: <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 form values when the email is created. For a template topic named =<nop>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 %TWISTY{showlink=" Show code" hidelink=" Hide code" showimgleft="%ICONURLPATH{toggleopen}%" hideimgleft="%ICONURLPATH{toggleclose}%" mode="div"}% <verbatim> <form enctype="application/x-www-form-urlencoded" name="mailform1" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST"> <fieldset> <legend><b>Send Email</b></legend> <div class="foswikiFormSteps"> <div class="foswikiFormStep"> <h3>To:</h3> <input class="foswikiInputField" id="to" name="to" size="30" type="text" value="%URLPARAM{"to"}%" /> </div> <div class="foswikiFormStep"> <h3>CC:</h3> <input type="text" class="foswikiInputField" id="cc" name="cc" size="30" value="%URLPARAM{"cc"}%" /> </div> <div class="foswikiFormStep"> <h3>Subject:</h3> <input type="text" class="foswikiInputField" id="subject" name="subject" size="70" value="%URLPARAM{"subject"}%" /> </div> <div class="foswikiFormStep"> <h3>Message:</h3> <textarea class="foswikiInputField" cols="70" name="body" rows="6" style="width:100%">%URLPARAM{"body"}%</textarea> </div> <div class="foswikiFormStep"> <input type="submit" class="foswikiSubmit" value="Send" /> </div> </div> </fieldset> </form> %SENDEMAIL{ feedbackSuccess="Request sent, we'll contact you shortly." feedbackError="Could not send your message, please contact us." format="<div class=\"foswikiNotification\">$message</div>" }% </verbatim> %ENDTWISTY% <form enctype="application/x-www-form-urlencoded" name="mailform" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST"> <fieldset> <legend><b>Send Email</b></legend> <div class="foswikiFormSteps"> <div class="foswikiFormStep"> ---+++!! To: <input class="foswikiInputField" id="to" name="to" size="30" type="text" value="%URLPARAM{"to"}%" /> </div> <div class="foswikiFormStep"> ---+++!! CC: <input type="text" class="foswikiInputField" id="cc" name="cc" size="30" value="%URLPARAM{"cc"}%" /> </div> <div class="foswikiFormStep"> ---+++!! Subject: <input type="text" class="foswikiInputField" id="subject" name="subject" size="70" value="%URLPARAM{"subject"}%" /> </div> <div class="foswikiFormStep"> ---+++!! Message: <textarea class="foswikiInputField" cols="70" name="body" rows="6" style="width:100%">%URLPARAM{"body"}%</textarea> </div> <div class="foswikiFormStep"> <input type="submit" class="foswikiSubmit" value="Send" /> </div> </div> </fieldset> </form> %SENDEMAIL{ feedbackSuccess="Request sent, we'll contact you shortly." feedbackError="Could not send your message, please contact us." format="<div class=\"foswikiNotification\">$message</div>" }% %ADDTOHEAD{text="<style type=\"text/css\"> #patternPage fieldset { border:1px solid #ddd; padding:1em } </style> "}% ---+++ Example with <nop>FormPlugin This form asks for user information and validates that the fields are filled. %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" }% <fieldset style="border:1px solid #ddd; padding:1em"> <legend><b>Send Email</b></legend> %RED%*%ENDCOLOR% All fields are required. %FORMELEMENT{ name="Subject" type="hidden" default="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:" }%%FORMELEMENT{ name="body" type="textarea" rows="10" cols="80" cssclass="foswikiHidden" default="From: $Name Email: $Email" }%%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." }% </verbatim> %ENDTWISTY% %STARTFORM{ name="mailForm" action="%SCRIPTURL{sendemail}%/%WEB%/%TOPIC%" method="POST" }% <fieldset style="border:1px solid #ddd; padding:1em"> <legend><b>Send Email</b></legend> %RED%*%ENDCOLOR% All fields are required. %FORMELEMENT{ name="Subject" type="hidden" default="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:" }%%FORMELEMENT{ name="body" type="textarea" rows="10" cols="80" cssclass="foswikiHidden" default="From: $Name Email: $Email" }%%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." }% ---++ 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 [[%SYSTEMWEB%.DataForms][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: <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="foswikiHidden" cols="80" rows="6"> Title: %FORMFIELD{"Title"}% Summary: %FORMFIELD{"Summary"}% </textarea> </verbatim> #PluginTest ---++ Plugin test * !SendEmailPlugin is %IF{"context SendEmailPluginEnabled" then='%GREEN%enabled%ENDCOLOR%' else='%RED%not enabled%ENDCOLOR%'}%. #PluginSettings ---++ Plugin Settings <!-- * Set SHORTDESCRIPTION = Send e-mails through an e-mail form --> * Plugin settings are set in [[%SCRIPTURLPATH{configure}%#SendEmailPlugin$Extensions][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 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. Use "Find More Extensions" to get a list of available extensions. Select "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 http://foswiki.org/Support/ManuallyInstallingExtensions for more help. ---++ Plugin Info | Plugin Author: | Foswiki:Main.ArthurClemens | | Copyright: | © 2007-2010 Arthur Clemens; 2008 Michael Daum | | License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) | | Version: | 1.5.4 | | Release: | 1.5.4 | | Change History: | <!-- versions below in reverse order --> | | 15 Mar 2013 | 1.5.4 Michael Daum: don't send an empty CC; fix adding css to the header | | 25 Aug 2011 | 1.5.3 Fixes a bug in the example form. | | 13 Mar 2010 | 1.5.2 Improved error feedback and documentation. | | 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. | | 12 Mar 2009 | 1.3 Foswiki version. | | 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. | | Foswiki Dependency: | None | | CPAN Dependencies: | none | | Other Dependencies: | none | | Perl Version: | 5.005 | | Plugin Home: | http://foswiki.org/Extensions/%TOPIC% | | Support: | http://foswiki.org/Support/%TOPIC% | | Development: | http://foswiki.org/Development/%TOPIC% |
Attachments
2
Attachments
2
Topic attachments
I
Attachment
Action
Size
Date
Who
Comment
png
screenshot.png
manage
16.4 K
08 Jan 2010 - 23:53
UnknownUser
css
sendemailplugin.css
manage
0.3 K
21 Mar 2009 - 22:12
UnknownUser
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r1
|
B
acklinks
|
V
iew topic
|
Edit
w
iki text
|
M
ore topic actions
Topic revision: r1 - 08 Jan 2010,
ProjectContributor
System
Log In
or
Register
Toolbox
Users
Groups
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
User Reference
BeginnersStartHere
TextFormattingRules
Macros
FormattedSearch
QuerySearch
DocumentGraphics
SkinBrowser
InstalledPlugins
Admin Maintenance
Reference Manual
AdminToolsCategory
InterWikis
ManagingWebs
SiteTools
DefaultPreferences
WebPreferences
Categories
Admin Documentation
Admin Tools
Developer Doc
User Documentation
User Tools
Webs
Cosmo
Main
Sandbox
System
English
Français
Polski
Copyright © CC-BY-SA by the contributing authors. All material on this collaboration platform is copyrighted under CC-BY-SA by the contributing authors unless otherwise noted.
Ideas, requests, problems regarding Foswiki?
Send feedback