iASP_Mail Component

Overview

iASP-Mail allows you to send SMTP mail directly from a Web page. Features include:

  • SMTP (sending) messages
  • Multiple file attachments supporting MIME and UUencoding ASCII and ISO-8859-1 character sets
  • Special Header Support (Standard X-Priority headers, MS Mail (including Exchange) priority headers, Urgent header, ConfirmReading and ReturnReceipt Headers)
  • Custom ContentType headers
  • Word wrap (customizable)
  • Subject line encoding for 8bit message subjects
  • Redundant SMTP servers (If the primary SMTP server is down, the secondary server is used)
  • Multiple concurrent users

Use the following links to view the details:

iASP_Mail Installation

To use this iASP component you just need to move the jar file into ClassPath.

Simple Mail Example

It is simple to use the component. Follow the steps below:

  1. Create the object
  2. Set a few properties
  3. Call the SendMail method

The following code demonstrates how to use iASP_Mail from VBScript. In this example George from George Handky wishes to send an email to John Smith. George mail server is located at mailhost.halcyonsoft.com.

Set mail = Server.CreateObject("SMTPsvg.Mailer")
mail.FromName   = "George Handky Corp."
mail.FromAddress= "George@halcyonsoft.com"
mail.RemoteHost = "mailhost.halcyonsoft.com"
mail.AddRecipient "John Smith", "jsmith@halcyonsoft.com"
mail.Subject    = "Great SMTP Product!"
mail.BodyText   = "Dear Stephen" & VbCrLf & "Your widgets order has been processed!"
if mail.SendMail then
  Response.Write "Mail sent..."
else
  Response.Write "Mail send failure. Error was " & mail.Response
end if

We can determine whether the mailing process is successful or not by checking the result of the SendMail method.

Form Handling

All or partial input for a message may come from a form. For example, a form posted to the server with a request method of GET (i.e. <form action="/scripts/iASP_Mail.asp" method=get>) may provide the message recipient's email address, subject and message text as follows:

mail.AddRecipient Request.QueryString("ToName"), Request.QueryString("ToAddress")
mail.Subject   =  Request.QueryString("Subject")
mail.BodyText  = Request.QueryString("MsgBody")

The form may also use the POST method (i.e. <form action="/scripts/iASP_Mail.asp" method=post>) in which case the code would look as follows:

mail.AddRecipient Request.Form("ToName"), Request.Form("ToAddress")
mail.Subject   =  Request.Form ("Subject")
mail.BodyText  = Request.Form ("MsgBody")

You can use any mixture of static and dynamic data when setting the components properties as dictated according to your needs. For example, you may wish to send the mail to a single user. In this case you could modify the code to look something like this:

mail.AddRecipient "John Smith", "jsmith@halcyonsoft.com"
mail.Subject   =  Request.QueryString("Subject")
mail.BodyText  = Request.QueryString("MsgBody")

Generic Form Handling

In some cases users may wish to use a number of different forms to send email with the same block of code. iASP allows you to loop through each QueryString or Form variable and append each one to string variable which is then assigned to the BodyText property. Please NOTE: iASP_Mail cannot control the order that these variables are returned in. This is a function of ASP, not iASP_Mail. ASP takes the form variables and creates the appropriate Request collection (QueryString or Form) and stores the data in an order that iASP_Mail cannot change. If you use this method you must accept ASP's order.

strMsgHeader = "Form information follows" & vbCrLf
for each qryItem in Request.QueryString
   strMsgInfo = strMsgInfo &  qryItem & " - " & request.querystring(qryItem) & vbCrLf
next
strMsgFooter = vbCrLf & "End of form information"
mail.BodyText = strMsgHeader & strMsgInfo & strMsgFooter

Setting Mailer Priority

There are a couple of headers that can be modified to set message priority.

The Priority property sets the message priority on a scale of 1 to 5. A priority of 1 means HIGH. A priority of 3 means NORMAL and a priority of 5 means LOW. In addition, you can also set the Urgent property if the message status is urgent. The Urgent property is a true/false property.

Using the DateTime Property

The component creates a Date/Time value for the message based on the calculated GMT time. The DateTime property was added to allow users to set a custom date/time timezone. The following code demonstrates how to set the DateTime to US Central Standard Time. By slightly altering the code you can adjust this to work for your own timezone.

function DayName (intDay)
  select case intDay
    case 1
      DayName = "Sun"
    case 2 
      DayName = "Mon"
    case 3 
      DayName = "Tue"
    case 4 
      DayName = "Wed"
    case 5 
      DayName = "Thu"
    case 6 
      DayName = "Fri"
    case 7 
    DayName = "Sat"
  end select
end function

function MonthName (intMonth)
  select case intMonth
    case 1
      MonthName = "Jan"
    case 2
      MonthName = "Feb"
    case 3
      MonthName = "Mar"
    case 4
      MonthName = "Apr"
    case 5
      MonthName = "May"
    case 6
      MonthName = "Jun"
    case 7
      MonthName = "Jul"
    case 8
      MonthName = "Aug"
    case 9
      MonthName = "Sep"
    case 10
      MonthName = "Oct"
    case 11
      MonthName = "Nov"
    case 12
      MonthName = "Dec"
  end select
end function

[set other mail properties]
mail.DateTime = DayName (WeekDay(Date)) & ", " & Day(Date) & " " 
& MonthName(Month(Date)) & " " & Year(Date) & " " & FormatDateTime(Now, 4) & " -0600 (CST)"
mail.SendMail

Notes on Creating the Mail Object

You can create the mail object at two different points in time:

  • Immediately before sending an email
  • At the session scope and saved as a session object

You will have to decide when and where it is appropriate to create the object based on your particular application. If you aren't sure which way to create the object reference, or for typical usage, you should create the object immediately before sending your email. Your code would look like this:

Set mail = Server.CreateObject("SMTPsvg.Mailer")
... [Set properties]
if mail.SendMail then ...

Creating these local references, as demonstrated above, allow you to use the object on multiple application threads at the same time.

To create an object reference at the session level, your code might look something like this:

if Not IsObject (session("Mailer")) then
  Set mail = Server.CreateObject("SMTPsvg.Mailer")
  Set session("Mailer") = mail
else
  Response.write "Cached session object reference being used<p>"
  Set mail = session("Mailer")
end if

Multiple Host Support

iASP_Mail provides one host property to set up remote SMTP server addresses. The RemoteHost property should be set to your primary and secondary server address separated by semicolons. In the event that the primary server is down, iASP_Mail will attempt to use the secondary server. For example,

mail.RemoteHost = "mailhost.halcyonsoft.com;mailhost.anotherisp.com"

iASP_Mail Properties

Property

Description

BodyText The message body text. To clear the text once you have set it use the ClearBodyText Method.
CharSet The character set. By default the char set is US Ascii

Valid values:

  • 1 = US Ascii
  • 2 = ISO-8859-1
ConfirmRead The ConfirmReading flag. If this is set to true AND the recipients email program supports

this feature (and it is enabled) the recipients email program will send a notice back to the FromAddress confirming that this email has been read.

ContentType The ContentType property allows you to set the ContentType header of the message's BodyText. If, for example, you wanted to send HTML as the message's body, you could set ContentType = "text/html" and Email programs that support HTML content could properly display the HTML text.

NOTE: The ContentType property is ignored if you have file attachments.

CustomCharSet If you wish to use a character set besides the included types you can set CustomCharSet to a character set string.
DateTime iASP_Mail will, by default, create a Date/Time header for your local system using GMT. If you would like to override the date/time calculation set the DateTime property to a valid date/time string in the format defined by RFC 822 & RFC 1123.
Encoding Unsupported
Expires If the component is an evaluation version the expires property will return the date that the component quits functioning.
FromName The message originator's name.
FromAddress The message originator's email address.
IgnoreMalformedAddress Defaults to false. When false iASP_Mail will check for '@' in the email address for calls to AddRecipient, AddCC and AddBCC. An error would be returned in the Response property. When this property is set to true iASP_Mail will not perform any address syntax validation. If you are using iASP_Mail to send a message through an SMS gateway or fax system you may need to set this property to true.
IgnoreRecipientErrors Defaults to true. If true iASP_Mail will ignore error messages returned by the SMTP server for invalid addresses. This is useful when a mailing is addressed to a number of recipients.
Live Unsupported.
Organization Sets the Organization header in the message.
PGPPath Unsupported
PGPParams Unsupported
Priority Sets the message priority. Priorities are 1-5 and are reflected in the X-Priority

Valid values:

  • 1 - High
  • 3 - Normal
  • 5 - Low
RemoteHost The remote SMTP host that the message will be sent through. This is typically an SMTP server located at your local ISP or it could be an internal SMTP server on your companies premises. Up to 3 server addresses can be specified, separated by a semicolon. If the primary server is down the component will attempt to send the mail using the secondary server and so on.
ReplyTo The ReplyTo property allows you to specify a different email address that replies should be sent to. By default mail programs should use the Reply-To: header for responses if this header is specified.
Response The Response property returns any error messages that may occur.
ReturnReceipt The ReturnReceipt flag. If this is set to true AND the recipients SMTP server supports

this feature (and it is enabled) the recipients SMTP server will send a notice back to the FromAddress confirming that this email has been delivered.

SMTPLog If you need to debug the session give a log file name here. Make sure the IUSR_XYZ IIS user has security that allows the component to write to this file. Warning: Do not use this setting in situations where multiple users can access this component at the same time. This is for single user debugging ONLY!
Subject The message subject.
SuppressMsgBody The SuppressMsgBody property is true by default and is used in conjunction with the SMTPLog property. When SMTPLog is set to a file and SuppressMsgBody is true the log file receives a copy of the message text. If SuppressMsgBody is false the message text is not sent to the log.
TimeOut Timeout is the maximum time that iASP_Mail should wait for a response from the remote server. The default is 30 seconds.
Urgent The urgent flag sets the X-Urgent header in the outgoing message. Not all mail readers support this flag.
UseMSMailHeaders MS-Mail priority headers, by default, are sent in addition to the standard SMTP priority headers. You can turn MS-Mail headers off with this property
Version Gets the internal component version number.
WordWrap The WordWrap property is off by default. Setting WordWrap to true causes the message body to wordwrap at the position specified by the WordWrapLen property.
WordWrapLen The WordWrapLen property is set to 70 by default. You can modify the position that wordwrap occurs by changing this value.

iASP_Mail Methods

Method

Parameters

Return Value

Description

SendMail None True/False based upon success or failure. The SendMail method attempts to send the email.
AddRecipient mail.AddRecipient "Jay Jones", "jayj@halcyonsoft.com" True/False based upon success or failure. Adds a new recipient, as shown in the message's To: list.
ClearRecipients None N/A Clears any recipients assigned to the To list.
AddCC mail.AddCC "Jay Jones", "jayj@halcyonsoft.com" True/False based upon success or failure. Adds a new recipient, as shown in the message's CC list.
ClearCCs None N/A Clears any recipients assigned to the CC list.
AddBCC mail.AddBCC "Jay Jones", "jayj@halcyonsoft.com" True/False based upon success or failure. Adds a new Blind Carbon Copy recipient. BCC recipients are not shown in any message recipient list.
ClearBCCs None N/A Clears any recipients assigned to the BCC list.
ClearAllRecipients None N/A Clears all recipients assigned to the To, CC and BCC lists.
AddAttachment Filename to attach to message. N/A Adds attachments to current mailing. You must use an explicit path to attach files.
ClearAttachments None N/A Clears any attachments that were previously set.
ClearBodyText None N/A Clears any text assigned to the message's body which may have been set previously by using the BodyText property.
ClearExtraHeaders None N/A Clears any X-Headers that were set by use of AddExtraHeader.
AddExtraHeader A string value that forms a proper SMTP X-Header True/False based upon success or failure. Adds extra X-Headers to the mail envelope.
GetBodyTextFromFile A String value of pathname,A boolean value (optional) for erase.A boolean value (optional) for showwindow. N/A Loads message's body text from a file. Optionally runs PGP on the message text.
EncodeHeader strValue strValue encoded as String Encodes a string in RFC1522 format to provide support for 8bit mail headers such as 8bit subject headers.
GetTempPath N/A strPath Returns the path set up by the OS for temporary mail files.

If you require technical support please send complete details about the problem you are having to support@halcyonsoft.com.


Copyright © 1998-2002, Halcyon Software Inc. All rights reserved.