How to create a mail-sending site:
Site Content:
Explanation of the steps to be processed:
- Design your HTML site containing the mail-sending form. The mailwebform_testexample.html
(view /
source) site delivered with the distribution is a
well-commented example.
- The mail is delivered using your HMTL form. This form must have an action attribute pointing to
"mailwebformservlet", and the method attribute may be "get" or "post".
Example: http://www.yourserver.com:8080/mailwebformservlet
If you don't know the exact URL to be put into the action attribute, ask the MailWebForm administrator.
- Absolutely required elements of the HTML form:
1. your provider name in a hidden input tag "provider", as assigned by the MailWebForm administrator
2. the sender's "fromEmail" input tag, where the sender must enter his e-mail address
3. the "text" input (or textarea) tag which contains the message body
- Optional elements are:
1. the "fromName" input tag, allowing the sender to enter his name
2. the "subject" input tag, defining the subject of the mail to be sent
3. any additional HTML input tag, visible or hidden! Those may inform the provider about e.g. the sending site
itself, the sex of the sender or whether he'd like to receive more information or whatever. If your template property
isn't defined, those additional attributes are listed at the beginning of the text of the generated mail. (If you'd
like to use a template that defines the look of the generated mails, refer to the section how to use
a mail template.)
The table below provides an overview of the discussed HTML form parameters.
- Your individual properties are stored in a file as shown below. It contains the
information about where to direct the user to after sending the mail (in case of success or error) and to which name
and address the mails are sent to. To prevent web site visitors from abusing MailWebForm, a form can send mails to
the specified address only. But don't worry: MailWebForm allows you to edit those properties through a web-based GUI!
Ask your MailWebForm provider for the URL to connect to the so-called admin tool as well as for the password to log in
(the user name equals to your provider name).
Table with the list of form parameters processed by MailWebForm:
parameter name |
parameter value
| required |
example |
provider |
<yourprovidername> |
yes |
<input type="hidden" name="provider" value="test"> |
fromName |
<entered by the user> |
no |
<input type="text" name="fromName"> |
fromEmail |
<entered by the user> |
yes |
<input type="text" name="fromEmail"> |
subject |
<entered by the user> |
no |
<input type="text" name="subject"> |
text |
<entered by the user> |
yes |
<textarea wrap="virtual" name="text"></textarea> |
How to use a mail template:
MailWebForm is able to process template files to allow the provider to define the layout of the generated mails.
Notes:
- MailWebForm generates plain text mails only! Therefore it won't make sense to use a HTML file as a template.
- Each of the optional parameters defined in your mail-sending site as well as the (required) "text" parameter
may go into this template, using a placeholder like
${<url-parameter-name>}
. Important: The names of
the placeholders must match the names of the optional parameters defined in your HTML site (case-insensitive check)!
- Important: If you don't add a placeholder for the "text" parameter to your template, the message text
won't be contained in the generated mail!
- If you add a placeholder to your template that doesn't match the name of an input of your mail-sending site, the
placeholder will be replaced with an empty string, i.e. nothing.
Example of a simple mail template containing two optional parameters named info
and address
as well
as the text entered by the user
Wants to receive additional information? ${info}
Address of the sender: ${address}
Text entered by the sender:
---------------------------
${text}
Example of a configuration parameter file's content:
Notes:
- Comment lines in a property file start with a "#".
- Do not change the parameter names!
- Each property is optional! Add only the values you want to define.
- In the example below, each property is defined, i.e. a value is given after each of the "=" signs. If a
value shall remain undefined, leave the part after "=" sign empty or add a "#" at the beginning of
the line.
# the URL that a client shall be redirected to in case of successful sending of the email
SUCCESS_URL=http://www.myserver.tld:8080/mysite/mail_sent_successfully.html
# the URL that a client shall be redirected to in case an error occurred during sending of the email
ERROR_URL=http://www.myserver.tld:8080/mysite/error_while_sending.html
# an optional name value (leading the to-address) that overrides the default value set by the system administrator.
TONAME=MailWebForm Test Account
# an optional address value that overrides the default to-address set by the system administrator.
TOADDRESS=test_account@mail_backup.mysecondserver.tld
# the value of the SMTP host to use; may be disallowed to overwrite by the system administrator
SMTP_HOST=mail_backup.mysecondserver.tld
# the value of the SMTP port to use (typically 25), but we use a proxy for this example; may be disallowed to
# overwrite by the system administrator
SMTP_PORT=2525
# the name of a mail template file that shall be processed (file name only, without path)
TEMPLATE=test.template