Introduction

SEND IT! is an email engine that allows you to send your form data to email addresses, plus much, much more. SEND IT! is an Intel binary executable for Windows 95 and Windows NT. 

Features

SEND IT! is feature rich. It contains the following:

• Template formatted Email Messages -- using a template, the email message can be formatted to suit your needs.
• Template formatted Save Results -- using a template, the fields can be saved in a format of your choosing. This can be HTML, comma delimited (CSV), Tab delimited, etc.
• Confirmation Page with field data substitution -- a confirmation page is displayed upon the successful conclusion of the SEND IT! program. The Confirmation page can also serve as a template with field values, computations displayed on the page.
• Required Field Checks -- Each incoming field can be required to be filled in with some value.
• Field Validation using pattern matching -- each incoming field's data can be validated against a pattern to ensure proper formatting of incoming data.
• Calculation Parsing and Formatting -- Calculations can be made using incoming field data, and the resulting value can be formatted and used in any of the template files.
• Multiple Recipients -- Multiple recipients can be specified to receive the email message.
• Courtesy Copies -- Multiple courtesy copy recipients can be specified.
• Blind Courtesy Copies -- Multiple blind courtesy recipients can be specified.
• Range Checks for Numeric Values -- Checks that a field is between x and y values inclusive.
• Default Values -- Default values may be supplied for items that are not sent.
• Confirmation Email -- A confirmation email can be sent to your visitor using a separate template file.

Also, SEND IT! can be used to require field entry, validate the entry, and save the data in a defined format without sending an email message.

Each of these features will be covered in detail.

Installation

To install SEND IT! place the sendit.exe file into a folder that allows execution of CGI scripts. That's all there is to it. There are no system files, parameter files, etc.

For FrontPage 2000 Users: In the FrontPage Editor, with the folder list displayed (View | Folder List), if a cgi-bin folder does not already exist, create one by selecting the first entry in folder list and clicking on:

1. File
2. New
3. Folder
4. Enter a name for the folder (cgi-bin)
5. Right click on the folder just created
6. Click Properties and the following dialog will appear

7. Click the Allow scripts or programs to be run.
8. Click OK

Now import the sendit.exe file into the newly created directory.

1. Double click the just created folder to open it.
2. File
3. Import -- the import dialog will appear

4. Click Add File
5. Locate the sendit.exe file on your hard drive.

6. Double click sendit.exe
7. Click the OK in the Import dialog

Now you should be ready to use SEND IT!

Calling the CGI program (sendit.exe)
To call the SEND IT! in your forms action line, specify the location that you placed sendit.exe. For example, if sendit.exe was placed into the cgi-bin directory of your web site, then the form tag would look like this.

<form action="cgi-bin/sendit.exe" method="POST">

For FrontPage 2000 Users: To include the sendit.exe into your forms, right click inside the dashed area of the form. Click Form Properties and the following dialog box will appear:

Select Custom ISAPI, NSAPI, or CGI Script as the form handler, click Options.

Enter the location of the sendit.exe file as the action and set the Method to POST if not already set. Click OK and the Form Properties dialog will reappear.

Next, click Advanced to enter the required reserved field names in the Hidden Fields box. Click Add and the following dialog box will appear.

Enter the reserved word in the Name text box and if the reserved word requires a value, enter it in the Value text box. To enter a reserved word that does not have a value, enter a space. The following are required reserved words: Either SMTP or NoMail and refer. See the Reserved Fields Names for a complete listing.

Click OK on all open dialog boxes.

Form Field Names
The letters $, !, and # are reserved when used as the first character of a field name. Names of standard form input fields cannot begin with the characters $, !, or #. They can contain spaces and other special characters and be up to 32 characters in length. Duplicate field names are not allowed except where noted. It is recommended that field names be descriptive of the data that they contain, e.g., First Name or Last Name, not First and Last. This is especially important if the field will be required to have an entry value, as the field name is used to re-request the entry by the visitor if the entry was not completed.

Field names that begin with a $ are reserved for the defining of calculation expressions (see Field Calculations below). Fields that begin with a # are reserved to contain a field validation pattern string (see Field Validation below). Fields that begin with a ! are reserved for the defining of a range (see Field Range Validation below).

There are three special preface tags that can be used with field names to denote special action by SEND IT!

req. -- If a form field name is prefaced with req., the SEND IT! engine will require the user to enter a value into the field. To use the field in a template, the field name should be used without the tag (req.). Example: <input type="text" name="req.First Name"> Example

def. -- Default values can be defined for a field by prefacing the field name with def.. This is most useful when the client browser does not pass in some form values. For example, an unchecked checkbox will neither send a value, nor will its field name be passed. If this field name were used in a template file, it would not be replaced and cause the template to look bad. By using a default value you can ensure that the template will look as you intend. Example:
<input type="text" name="def.Send Package" value="None Checked!">

env. -- Any form field that begins with env. followed by an environment variable name will be made available to the SEND IT! program for substitution in templates. This allows the web designer to display server and machine environment information without the SEND IT! program being dependent upon the server / machine environment. To use the field in a template, the field name should contain the preface env. followed by the environment variable. Example:
<input type="hidden" name=env.REMOTE_ADDR> Example

Some examples of useful environment variables are:

• DOCUMENT_NAME This variable is the complete local directory path of the current document.
• DOCUMENT_URI This variable is the local path of the current document referenced to the base directory of the webspace.
• QUERY_STRING_UNESCAPED This variable is the unescaped query string sent by the client browser, all shell-special characters escaped with \.
• DATE_LOCAL This variable is current local date and time.
• DATE_GMT This variable is the current Greenwich Mean date and time.
• LAST_MODIFIED This variable is the date and time of the last modification of the current document. _NAME This variable is the local computer name of the HTTP server.
• GATEWAY_INTERFACE This variable is the name/version of the Common Gateway Interface served on this HTTP server.
• SERVER_PROTOCOL This variable is the name/version of HTTP served on this HTTP server
• SERVER_PORT This variable is the IP port the HTTP server is answering on.
• REQUEST_METHOD This variable is the method by which the current document was requested.
• PATH_INFO This variable is the extra path info that is sent. This information is regarded as virtual (the path is relative to the base directory of the HTTP server).
• PATH_TRANSLATED This variable is the 'PATH_INFO' variable translated from virtual to local (physical) disk location. •SCRIPT_NAME This variable is the virtual path of the script being executed.
• REMOTE_HOST This variable is the host name of the remote client.
• AUTH_TYPE This variable is the authentication method used to validate the remote client.
• REMOTE_USER This variable is the user name used to validate authentication from the remote client.
• REMOTE_IDENT This variable is the remote user name if supporting RFC931 identification.
• CONTENT_TYPE This variable is the content type of the attached information in the case of a POST or PUT.
• CONTENT_LENGTH This variable is the length of the attached information in the case of a POST or PUT.
• HTTP_ACCEPT This variable is a comma separated list of mime types that are accepted by the remote browser.
• HTTP_USER_AGENT This variable is the name of the remote client browser software.
• HTTP_REFERER This variable is the URL of the HTML document which referred the remote client to this document.
• FROM This variable is the name (most likely the email address) of the remote client user.
• FORWARDED This variable is the name of the proxy server through which this document is being processed.
• ACCEPT_LANGUGE This variable lists the human languages that are acceptable to the remote client.
• HTTP_COOKIE This variable contains the cookie sent by the remote client.

(Use the ENV reserved Field name in combination with the NoMail to display the servers available environment variable names.) Example

Reserved Field Names
NoMail -- no email messages will be sent. Required if SMTP is not present.

SMTP -- the Simple Mail Transport Protocol server domain name. This is most often your email server used to send email. <input type="hidden" name="SMTP" value="mail.server.com"> Required if NoMail is not present.

refer -- (Required) the location of the page to be displayed next. Please note that a FrontPage Confirmation Page will work with this feature. <input type="hidden" name="refer" value="confirmation.htm"> Note that links to images and hyperlinks must be absolute references - image/yourimage.gif should be /images/yourimages.gif.

RCPT -- the recipient of the email message. At least one must be defined with multiples allowed.
input type="hidden" name="RCPT" value="sales@yourdomain.com"   Required if NoMail is not present.

From -- the email address of the person sending this email. It is normally included in the form as the visitor's email address. It is validated using the pattern "[\a]+@[\a.]+" (see Field Validation below).The from field allows the receiver of the email to reply just by doing a Reply to Sender.
Your email address: <input type="text" name="From" >

DEBUG -- if the debug parameter is defined, SEND IT! will display the passed form field name value pairs that it receives, in the order received. This information is formatted so that if required fields are present in the form they are shown in red. Example output
<input type="hidden" name="DEBUG" value=" "> Note for FrontPage users -- FrontPage will not allow you to not enter a value for a hidden input field, so just enter a single space.

LineWrap -- defines the character position that a line in an emailed template should be wrapped to the next line. This will not cause a line to be concatenated to another line. The point that the line is broken is not tested for word boundary and many break inside a word. All wrapping occurs after field value subsitution. Field value subsitution may expand or contract a lines length. The default line length is 2048 characters.
<input type="hidden" name="LineWrap" value=80>

ENV -- if the env parameter is defined, SEND IT! will display SEND IT!'s environment variables. Example output <input type="hidden" name="ENV" > Note for FrontPage users -- FrontPage will not allow you to not enter a value for a hidden input field, so just enter a single space.

CC -- holds courtesy copy email address to send a copy of this email message. One or more can be present in the form. <input type="hidden" name="CC" value="csr@yourdomain.com">

BCC -- holds blind courtesy copy email address of a recipient of this email message. One or more can be present in the form. <input type="hidden" name="BCC" value="csr@yourdomain.com">

Subject -- the subject of the email message <input type="hidden" name="Subject" value="Big Order!"> If not present, then the email is sent with a subject of "No Subject Provided".

Header -- An HTML file that becomes the header for informational message produced by SEND IT!, e.g., required fields, range values are incorrect, or a field does not match a field validation pattern. All the information in the file up to but not including the </body> tag is used. <input type="hidden" name="Header" value="header.htm"> Example output.

Footer -- An HTML file that becomes the footer for informational messages produced by SEND IT! (see Header). All information after the <body> tag is included. <input type="hidden" name="Footer" value="footer.htm"> Example output.

DateTime -- DateTime is an intrinsic field that may be used to display the date and time of the message. It is formatted according to RFC 1152 (Do Not Define This Field) Example.

EmailVisitor -- Tells SEND IT! to send a single email to the visitor using the From field. The value of EmailVisitor is the location of a template to be used for this e-mail.
<input type="hidden" name="EmailVisitor" value="visitortemplate.htm">

VSubject -- the subject to be used for the EmailVisitor email. If not provided, then defaults to Subject
<input type="hidden" name="VSubject" value="Your J-BOTS Are Ready">

VFrom -- the from value to be used so that the visitor can reply to this email message. If not provided, then defaults to From -- an email sent from the person being emailed.
input type="hidden" name="VFrom" value="sales@websunlimited.com"

Save Results File -- the location to save the forms data. The save results file is used to save the values passed in from the form. <input type="hidden" name="Save Results File" value="saveresults.htm">
All new information is appended to the end of this file. Example.

SaveTemplate -- the location of a file to use as a template for the save results file (see Template File Formatting). <input type="hidden" name="SaveTemplate" value="savetemplate.htm"> Example.

Timeout -- the value in seconds that the system will wait for the saveresults file to become free if in use by another process. It defaults to 5.
<input type="hidden" name="Timeout" value="8">

Adding Reserved Field Names to a form
Almost all reserved field names, with the exception of the From field, are used in hidden fields, i.e., not visible to your visitor. To include those that you need, just enter the input tags for each. For example:

<input type="hidden" name="Reserved Field name" value="Field Value">

Replace the Reserved Field name with one the reserved field names above and replace the field value with the value required by the reserved field name if it is required.

Right click inside the dashed form area, then click properties and the following dialog will appear:

Click Advanced and the following dialog will appear:

Click Add and the following dialog will appear.

Template File Formatting
A template file is a plain ASCII file. It can be created using NotePad or Wordpad. Template files can contain form field names in square brackets that will be replaced during the output phase of the SEND IT! program. For example, if you have a form that contains "First Name" and a "From" (minus the quotes) as field names, then if the SaveTemplate template page were to contain the following:

[First Name]
Welcome to the SEND IT! Society. We have recorded your email address as [From] into our database and will notify you of any changes in the by-laws.

Thanks again.

SEND IT! Society

Substitution will expand or contract the [fieldname] parameter to the size of the actual value data passed in from the form. It is advisable to set the maxlength attributes of entry fields or use the field validation to control the size. A line of text can not contain more than 4096 characters when it is fully expanded with its substitutions. It will be truncated to 4096 characters if expansion tries to increase it beyond this limit. Fields must be contained on a single line.

Your date of birth is [Your Date of Birth]. -- OK

Your date of birth is [Your Date
of Birth]. -- will not work

Substitution can be used in the following pages:

• Header

• Footer

• Mail Template

• EmailVisitor Template

• SaveTemplate

• refer

Mail Template File
The mail template file provides the formatting structure for the email message to be sent to the RCPT, CC, and BCC recipients. The mail template can be formed using an ASCII editor, following the guidelines under Template File Formatting.

The template file is specified by suffixing the action line of the form tag with the location of the template file relative to the root of the domain. For example, if the sendit.exe program is in cgi-bin/sendit.exe and the mailtemp.txt is in the root, then the form tag would look like the following:

Receipt/Visitors Template
The visitor template file provides the formatting structure for the email message to be sent to the visitor. The visitor is defined to be the email address contained in the From reserved field name. The mail template can be formed using an ASCII editor, following the guidelines under Template File Formatting.

The visitors template is defined by the EmailVisitor reserved field name. The value of this reserved word defines the location of the template file. This location is relative to the root of the domain. An example:

Save Results Template File
The save template file provides the formatting structure for the data to be save to the web site's disk storage area. The files location is specified by the reserved field name SaveTemplate. The location is relative to the root of the domain. For example, if the save results template is stored at _private/save.txt, the input tag would contain:

The location of the saved data is specified by the Save Results File field name. It also is relative to the root of the domain.

If a SaveTemplate is not included in the passed field names, the data is saved in columnar fashion in the Save Results File. If the Save Results file cannot be found, one will be created. If the file already exists, the information will be appended to the end of the file.

The template file can be created using any ASCII editor. An example of a comma delimited file with three fields (name, address, email) would be:

Note the double quotes to escape the inclusion of commas in the visitor's input.

Each visitor's data would be appended to the Save Results File in the order received.

If the file were going to be input into an Excel spreadsheet, where the first line would define the column name, then pre-create the Save Results File with the line.

Confirmation Page
The confirmation page is located by the refer reserved field name. The location specified must be relative to the root of the domain. For example, if the confirmation page is stored at _private/thanks.htm, the input tag would contain:

If the confirmation page contains field names in brackets, they will be replaced with the information passed in via the form. This can include field calculations, default values, etc.

Field substitution in the Confirmation page is allowed and works the same as any other template file. Please note that FrontPage and other html editors can and will break lines at unexpected places. If you have a substitution that is not working, look at the source to see if the [field name] is not split across two lines.

Note: Because the confirmation page is read and written by SEND IT!, the directory reference currently available to the browser is at the location of the sendit.exe file. This means that all image and hyperlinks must be relative to this directory. For example, if your images are stored in images relative to the root and if the sendit.exe were being run from cgi-bin relative to the root, then the image location would need to be specified as /images/myimage.gif. Links referring to pages at the root would need to be specified as href=/mypage.htm.

Field Validation
Field validation is specified using a pattern matching string. The pattern is matched against the field starting with the first character. If a match is not found, an error is produced and a descriptive message is displayed to the visitor.

The pattern is entered into the form as a hidden field with the same name as the field to be checked but beginning with a # sign. For example, if you have a phone field named phone, then the pattern would be named #phone. Please note that if the field to be checked is defined using the preface tags req. and def., these tags should not be used with field specifier field names -- use #name. Never use #req.name or #def.name.

A pattern is made up of a character or range of characters and optionally followed by an iterator. The characters can be comprised of:

a - match the lowercase character a.
[a-z] - match any of the lowercase characters a through z.
[0-9$*&^] - match any of the characters 0 through 9 and the special characters $, *, &, and ^
[^a-z] - match any character that is not a lowercase a through z character
\d - match any of the characters 0 through 9.
[^wer] - match any character but w, e, or r.
\- - match the character -.

Iterators:
Iterators define how many of the preceding characters (maybe a range of characters) need to be matched. If there is no match, then an error occurs and the visitor is shown where the error happen in the field data.

Examples of iterator usage:

a* - match zero or more of the character a.
[234]{3} - match at least 3 of the characters 2, 3, or 4 in any order.
[^\d]+ - match at least one character that is not 0 through 9.

An example:
A phone field that requires the visitor to enter a phone number consisting of a 3 digit area code, 3 digit prefix, and 4 digit suffix. Optionally, the visitor may enclose the area code in parentheses, have a space between the area code and prefix, and, may have a dash between the prefix and the suffix. So the visitor may enter any of the following:

4024318642
(402)4318642
(402) 4318642
(402) 431-8642
402 4318642
402 431-8642
402 431 8642

The pattern required to allow entry of all of the above options is:

(?[0-9]{3})? ?[\d]{3}-? ?[\d]{4}

Expression Parsing and Calculation
An expression can be entered into the available parameters by including a field that has a name beginning with a $ symbol, e.g., $expression1. The value of the expression can be any valid arithmetic formula using the operators ^,*,/,+,-, e.g. 4*5-3. The results of the expression will replace the formula. Parenthetical expressions can be used to change the order of precedence (^,*,/,-,+).

Any of the passed input fields can be used in the formula. For example if the fields Quantity and Price were passed in and an expression of $extended was defined with a value of Quantity*Price, the results would replace the formula with the extended amount. The results can be used in additional expressions as long as the results have been computed prior to their use, or the value used in the expression will be zero.

Expression fields are computed in left to right, top to bottom manner.

If a non-expression field is used which does not contain any numeric, then the value used will be zero for the fields value. If the field starts with a numeric, the numeric digits up to the first non-numeric, excluding the decimal point and the uniary symbols + and -, will stop the scan.

All values are converted to floating point numbers.

Expression Results Formatting
The expression field name can be suffixed by a format specfier. The format specfier is identified by a leading percent symbol (%) followed by a total format width, a period, then the number of decimal places to the right of the decimal point. For example, to have a field that is 10 characters wide and 3 places following the decimal point, the field name would be: $expression1%10.3. This would create a field 10 characters wide with the decimal point in character position 6 followed by decimal value of no more than three places. Default is for an unspecified width with a precision of 2 decimal places.

Range Validation
An input field value can be checked to see if it is in a numeric range. To specify the range, a field with the same name as the field to be validate is created but prefaced with a leading exclamation point (!), e.g., the field name weight then would be !weight and would contain the range allowed to be entered into weight.

The range bounds (lower and upper) are specified by including them separated by a comma, i.e., 120,150. The range may include leading + or - and a decimal point. The maximum characters, including the sign and decimal point, is 16.

In no case can the upper bound be less than the lower bound. The range is inclusive of the lower and upper bounds.

An example:
Your weight <input type=text name=req.weight>
<input type=text name=#weight value="[0-9]{3}">
<input type=text name=!weight value="100,175">

The first line requests the visitor to enter their weight, which is required by the system, followed by a field validation specfier that requires the field to contain three digits, zero through nine. Then a range check to see if the value entered was between 100 and 175 pounds, inclusive of 100 and 175.

Please note that even though the field, weight, has a preface tag of req., the preface is not used in the field validation definition nor the range validation.

System Processing Sequence
The order is:

1. Required fields

2. Default fields

3. Field pattern validation

4. Range validation

5. Calculations

Security Run Key
SEND IT! is licensed on a domain basis. What this means is that during the installation process you will be requested to enter the domain name that will be running SEND IT! Any attempt to run SEND IT! from another server will be met with a denial message.

This does not preclude you using SEND IT! on your local machine for testing purposes, i.e., SEND IT! will also allow for a domain IP of 127.0.0.1 or localhost.

Arithmetic Precision

Smallest positive number: 1.192092896e–07F

Largest positive number: 3.402823466e+38F

Minimum negative integer such that 10 raised to that number is a representable floating-point number. –37

Four fifths rounding is used for all numbers.

Error Messages
SMTP server error: %s -- The SMTP server returned an error message. The email was not sent and the program terminates. Correct the cause of the SMTP error.

Warning: Error reading from server pipe. %d bytes left to read -- SEND IT! was unable to read from the SMTP server input buffer. Contact support at Webs Unlimited.

This script should be used with an Internet browser -- The SEND IT! program can only be ran using a browser

This script should be referenced with a METHOD of POST -- The SEND IT! program expects it's input to be provided using the POST method. Check that the form is using a method of POST. SEND IT can not be ran from the browser location or address input line.

Field, "%s" contains an invalid character at position %d -- The field %s does not match the field validation pattern. The pattern stopped matching at the position indicated %d. Correct the input and continue.

Field, "%s" contains an invalid non-numeric character at position %d in numeric only field. -- The field contains a non-numeric character at position %s in a field that should only have numeric characters. Correct the input and continue.

%s must be equal to or greater than %s -- The input value entered into a range validated field contains a number less than the minimum allowed. Correct the input and continue.

%s must be less than or equal to %s -- The input value entered into a range validated field contains a number greater than the maximum allowed. Correct the input and continue.

The refer file, " %s" can not be found at %s. -- The file %s can not be found at the physical disk location %s. Make sure that the refer file specified location is relative to the domain root and is present.

The email template file %s can not found at %s -- The file %s can not be found at the physical disk location %s. Make sure that the email template file specified location is relative to the domain root and is present.

The save results template file, "%s" can not be found at %s -- The file %s can not be found at the physical disk location %s. Make sure that the save results template file specified location is relative to the domain root and is present.

The Header file, \"%s\" can not be found at %s -- The file %s can not be found at the physical disk location %s. Make sure that the Header file specified location is relative to the domain root and is present.

The footer file \"%s\" can not be found at %s <br> at %s The email template file %s can not found at %s -- The file %s can not be found at the physical disk location %s. Make sure that the email template file specified location is relative to the domain root and present.

A refresh key word was found in %s<br>Circumventing the intent of the refer page is not allowed! -- The refresh html tag is not allowed in a refer file. Remove the tag and continue.

Please complete the form. The following fields require entry: -- An informational message to the visitor listing the fields, by field name -- left to right, top to bottom, that require their input.

The iterator ({}) count range is invalid -- The count used in a count specfier {} is invalid. The most likely cause is that it is non-numeric.

The pattern %s is not valid at position %d because of -- %s -- The syntax check of a pattern as failed. Correct the condition causing the pattern to not follow syntax.

Socket Description: %s -- A description of the WinSock in use.

Socket error: %s -- The error message associated with Socket error: %d

Socket handle: %X -- The WinSock handle in use.

Socket error: %d -- The last error returned by WinSock.

SEND IT!: Error %d %s - %d -- A catastrophic error with the SMTP server or limited resources has abended the program.

• Failed to Start Sockets

• Failed to Resolve Host

• Failed to obtain socket handle

• Failed to Connect

• Failed to Send

• Failed to Receive

• Server Error

• Failed to resolve the host IP name

• Out of memory

• Unknown error

• Bad Message Contents

• Bad Message Subject

• Bad Message Destination

• Bad Message Return Path

• Bad Mail Host

• Bad Message File

Examples

1. Range Validation

2. Required Fields

3. Header / Footer w/ Required Fields

4. Passing Data Across Forms (data persistence)

5. Calculations and Formatting

6. Pattern Matching

7. EmailVisitor Options

8. DEBUG

9. ENV

10. Displaying Environment Variables

11. Save Results

12. DateTime

13. Using SEND IT! as a Drop Down Jump processor

14. An example to show how SEND IT! can be used to pass information to a javascript directly

15. Check box example

16. Create your own banner example