Calling the Form to Mail Script
The script is attached to a form by specifying action="email.php" method="post" in the form tag. All of the fields within the form (including hidden fields) will be passed to the email script for processing. The script has been designed to handle all of the fields that you pass to the script regardless of what names that you give them but a number of names have been assigned special meanings within the script. It is through the use of these special fields that you can define the format of the generated email.
The one field that your form must contain is one called replyemail. This field is used to set the from and reply-to addresses in the email.
All of the other special fields are optional and have default actions/values defined for them. The other special field names are as follows:
- destemail contains a list of addresses To: which the email is to be sent. This name only has a special meaning where $do = 1, 2, or 3. Addresses should be separated by commas or semi-colons. Where overriding the to address is blocked in the script configuration or where a field by this name does not appear in the form the default destination address will be used instead.
- dom specifies a default domain to which the emails are to be sent. If any of the addresses in the destemail field do not contain an @ then the address will be assumed to be at this domain. This field defaults to the first value specified in $ref.
- cc contains a list of destination addresses to which the email will be Cc:ed. Addresses should be separated by commas or semi-colons.
- bcc contains a list of the email addresses to which the email will be Bcc:ed. Addresses should be separated by commas or semi-colons.
NOTE the script limits the total recipients of an email (To: + Cc: + Bcc:) to a maximum of 25.
- metoo - where this field is present in the form the replyemail address will be added to the list of addresses in the cc field. By including this field in the form as a checkbox you allow the person filling out the form to decide whether or not to send themselves a copy of the email.
- ccsender - As with metoo including this field allows the person filling out the form to decide whether or not to send themselves a copy of the email. Where it differs from the metoo option is that when this option is used the email is sent separately with their email address in both the from and to fields. This conceals the real destination address while still allowing them to obtain a copy of the email that they sent. The cc and bcc fields should not be used at the same time as this field or those email addresses will receive both copies of the email.
- fmt(*) must be set to either text (to produce a plain text email) html for an HTML email or both (for a multipart plain text / html formatted email). If not specified the default is text. Can also be set to attach to create "form.txt" plain text file attachment instead (version 2.5+).
- url identifies the address of the page that is to be displayed after the email is sent. You would normally use a hidden field to supply the url information.
- subject - the subject of the email. If not specified then the email subject "Form Submission" will be used.
- header contains text (or html to be placed at the top of the email. If not specified then "The following information was entered:" will be used. You would normally use a hidden field to supply header information.
- template(*) contains a template of the text (or html) that will immediately follow the header text. The positions within this template text where data from other fields entered into the form should be substituted are identified by surrounding the appropriate name with tilde characters. For example if you want to substitute a field called age into a sentence you might put "I am ~age~ years old.". If using the template field then you need to make sure that all of the fields (apart from special fields) are referenced from within the template text otherwise the values will not be passed in the email. The template option doesn't work all that well with checkboxes since with a checkbox you either get a field value of "on" or no field at all. If using template you should use two radio buttons instead so that you can assign the two values that you want to use. If a template field is not supplied then instead of a formatted email you will get a list of all of the fields passed to the script (apart from the special ones) with the values of the fields alongside. You would almost always use a hidden field to supply template information.
- message contains text (or html) that will be substituted into the email immediately after the formatted information from the template (or list of field values).
- name contains the name of the sender of the email. This field will be treated the same as any non-special fields by being substituted into the template or included in the field/value list but will also be used to add regards, ~name~ after the message.
- footer contains text (or html) to appear at the bottom of the email. If not specified then the reply email address and the ip address of the computer that entered the form details will be used as footer text.
- include(*) allows you to specify a separate php file that will be processed after loading the posted parameters into an array but before building the email text thus allowing any formatting you like to take place. The simplest use of this option is to use the separate file to set all of the fields that you want to assign values to avoid having to specify them as hidden fields in the form.
- attach(*) allows you to specify a comma separated list of files to be attached to the email. You can specify .gif, .jpg, .jpeg, .png, .zip, .gzip, .gz, .tar, .pdf, and .txt files and the appropriate mime type will be used. Other file types can be attached but they may not be readable on the receiving system.
- embed(*) allows you to specify a comma separated list of images to be embedded into an html email. Simply specify ~embed0~ in the html source where you want the first image to be embedded, ~embed1~ for the second and so on. Unlike where you just reference online images, the actual images will be sent within the email and will show when the email is displayed even when the computer is not connected to the internet.
- mandatory(*) allows you to specify a comma separated list of input fields that will be tested to ensure that they contain a non-blank value before allowing the email to be sent.
- Any other fields named in the form will be substituted wherever they are referenced in the template field in producing a formatted email or will have the name and value listed in the email.
- The web(*) field will also be validated to make sure that it starts with http:// or https:// (version 3.6+).
I actually have two versions of the form to mail script, one free (for non-commercial use) and one I ask you to pay for (which can also be used with commercial web sites). Those parameters marked (*) are only available in the paid version.
