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
- Simple Mail Example
- Form Handling
- Generic Form Handling
- Setting Mailer Priority
- How to use the DateTime Property
- Notes about Creating the Mail Object
- Multiple Host Support
- About Upgrades
- iASP_Mail Properties
- iASP_Mail Components Methods
To use this iASP component you just need to move the jar file into ClassPath.
It is simple to use the component. Follow the steps below:
- Create the object
- Set a few properties
- 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 ifWe can determine whether the mailing process is successful or not by checking the result of the SendMail method.
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")
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
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.
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
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
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"
The latest version of the components is always available at http://www.halcyonsoft.com/. If a fee is associated with obtaining the upgrade it will be NOTED on that page.
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 ?C High
- 3 ?C Normal
- 5 ?C 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.
Method
Parameters
Return Value
Description
SendMail None True or False 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 None 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 None 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 None Clears any recipients assigned to the BCC list. ClearAllRecipients None None 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 None Clears any attachments that were previously set. ClearBodyText None None Clears any text assigned to the message's body which may have been set previously by using the BodyText property. ClearExtraHeaders None None Clears any X-Headers that were set by use of AddExtraHeader. AddExtraHeader A string value that forms a proper SMTP X-Header True or false. Returns true if X-Header was added. 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. None 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-2000, Halcyon Software Inc. All rights reserved.