##############################################################################
#                             FormMail v1.6                                  #
#                      Form to Email Gateway Script                          #
#                                                                            #
#                         Scripts Archive                                    #
#                    https://worldwidemart.com/scripts/                      #
##############################################################################

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!                         SECURITY WARNING                                  !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!                                                                           !
! This script is provided for HISTORICAL and EDUCATIONAL purposes only.     !
!                                                                           !
! The original FormMail had serious security vulnerabilities that were      !
! exploited by spammers for decades. This version includes basic fixes,     !
! but for production websites you should use modern alternatives:           !
!                                                                           !
! RECOMMENDED ALTERNATIVES:                                                 !
! - NMS FormMail: https://nms-cgi.sourceforge.net/                         !
! - Tectite FormMail: https://www.tectite.com/formmailpage.php             !
! - PHPMailer: https://github.com/PHPMailer/PHPMailer                      !
! - Formspree: https://formspree.io/                                       !
! - Netlify Forms: https://www.netlify.com/products/forms/                 !
!                                                                           !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

DESCRIPTION
-----------
FormMail is a generic WWW form to email gateway that parses the results of
any HTML form and sends them to specified email addresses.

FEATURES
--------
* Processes any HTML form and emails results
* Required field validation
* Email address validation
* Redirect after submission
* Customizable success/error pages
* Environment variable reporting
* Referer validation

REQUIREMENTS
------------
* Unix-based web server with CGI support
* Perl 5.x or higher
* sendmail or compatible mail transfer agent
* CGI.pm module

PACKAGE CONTENTS
----------------
FormMail.pl     - Main FormMail script
README          - This documentation file

INSTALLATION
------------
1. Upload FormMail.pl to your cgi-bin directory
2. Set permissions: chmod 755 FormMail.pl
3. Edit configuration variables:
   - @referers: List of domains allowed to use the form
   - @recipients: (Optional) List of allowed recipient addresses
   - $mailprog: Path to sendmail
4. Create your HTML form (see examples below)

CONFIGURATION
-------------
Edit these variables at the top of FormMail.pl:

@referers       - Domains allowed to use this script
@recipients     - Allowed email recipients (leave empty to allow form-specified)
$mailprog       - Path to sendmail (usually /usr/sbin/sendmail)

FORM FIELDS
-----------
Hidden fields you can use in your HTML form:

recipient       - (Required) Email address to send results to
subject         - Subject line of the email
redirect        - URL to redirect to after submission
required        - Comma-separated list of required fields
env_report      - Environment variables to include (REMOTE_HOST, etc.)
print_config    - Order of fields to print in email

EXAMPLE FORM
------------
<form action="/cgi-bin/FormMail.pl" method="POST">
    <input type="hidden" name="recipient" value="webmaster@yourdomain.com">
    <input type="hidden" name="subject" value="Contact Form">
    <input type="hidden" name="required" value="name,email,message">
    <input type="hidden" name="redirect" value="https://yourdomain.com/thanks.html">

    <label>Name: <input type="text" name="name"></label><br>
    <label>Email: <input type="email" name="email"></label><br>
    <label>Message:<br>
    <textarea name="message" rows="5" cols="40"></textarea></label><br>
    <input type="submit" value="Send">
</form>

SECURITY NOTES
--------------
1. ALWAYS set @referers to your domain(s)
2. Consider using @recipients to whitelist allowed addresses
3. Validate all user input
4. Keep Perl and modules updated
5. Monitor for unusual activity
6. Consider rate limiting

TROUBLESHOOTING
---------------
Problem: "Internal Server Error"
Solution: Check script permissions (755), verify Perl path, check error log

Problem: Email not received
Solution: Check $mailprog path, verify sendmail is working, check spam folder

Problem: "Invalid Referer" error
Solution: Add your domain to @referers configuration

HISTORICAL NOTES
----------------
FormMail was created in 1995 and became one of the most widely used CGI
scripts on the web. Unfortunately, it also became one of the most exploited
scripts due to email header injection vulnerabilities that allowed spammers
to use it as an open relay.

Key dates:
- 1995: FormMail created
- 1997: Version 1.6 released
- 2001: CVE-2001-0357 disclosed (email injection)
- 2002: FormMail listed as #3 attack vector (SecurityFocus)
- 2002: NMS project creates secure replacements

LICENSE
-------
Artistic License

##############################################################################
