Sierra Web Design ASPMail 2.x FAQ

Disclaimer
Please read this FAQ and understand this product fully before attempting to use it on your site. Contact us at webmaster@sierraweb.com or (702)833-9500 with any questions.

AspMail allows you to send mail using the standard SMTP protocol from any program that can use ActiveX/OLE components. Features include:

Changes in AspMail 2.0

AspMail 2.0 builds on the functionality of AspMail 1.0 by replacing the SMTP "plumbing" with an improved implementation, replaces a number of properties with methods to clarify email addressing, provides a complete type library and provides dual interface support. In addition to the changes:

1.) The RemoteHostB property was removed and combined with the RemoteHost property. AspMail can now try up to three SMTP servers in attempting to send an email. Seperate the different SMTP server addresses with a semicolon.

2) The Recipient, CC, and BCC properties have been replaced with AddRecipient, AddCC and AddBCC methods. This new scheme provides for better addressing. There are also 4 new methods: ClearRecipients [To:], ClearCCs [CC:], ClearBCCs [BCC:] and ClearAllRecipients which allow you to empty the recipient lists once addresses have been added. Please note that under AspMail 1.x recipient was a property but the AddRecipient family are methods. See the following docs for the proper calling convention.

Simple Mail Example

The following code demonstrates how to use AspMail from VBScript. In this example Joe from Joe’s Widgets wishes to send an email to John Smith at Tools Corp. Joe’s mail server is located at mailhost.localisp.net.

By testing the result of the SendMail method we can determine if the mailing process was successful or not.

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/AspMail.asp" method=get>) may provide the message recipient’s email address, subject and message text as follows:

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

You can use any mixture of static and dynamic data in setting the components properties as dictated by 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:

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. ASP 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.

Setting Mail 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 to this you can also set the Urgent property if the message status is urgent. The Urgent property is a true/false property.

How to Use 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.

Notes About Creating the Mailer Object

Sierra Web Design Note: we strongly recommend creating the mailer object immediately before sending email.

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:

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:

Multiple Host Support

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

PGP Support

Sending Mail from SQL Server

AspMail objects can be created from within T-SQL script using the automation support added in SQL 6.5. See the What's New in SQL Server 6.5 booklet, part 5, for details on how to create automation objects. T-SQL scripts are callable from a trigger so that messages can be sent out whenever data is modified.

Questions about AspMail

How do I determine a cause of mail failure?

Note about FromAddress: You must specify a value for the FromAddress property. Mail failure will occur without a FromAddress.

If the component can determine why the SendMail method failed, that information will be stored in the Response property. So, for example, to print that information to the clients browser you could add the following code:

if not Mailer.SendMail then
  if Mailer.Response <> ''" then
    strError = Mailer.Response
  else
    strError = "Unknown"
  end if
  Response.Write "Mail failure occured. Reason: " & strError
end if

Another fairly common problem is when a user reports that a specific feature is not working. For example BCC's may seem to never reach their destination. A valuable debugging tool is available with the SMTPLog feature. Assign a valid filename to this property and the contents of the SMTP transaction that occurs during a SendMail call will be recorded to this file. If you find that the SMTP transaction occurs without error then you should check elsewhere for the cause of mail delivery failure. Invariably the user finds that the BCC address was invalid or that the address was misconfigured. The SMTPLog feature allows you to verify if the transactions are complete and valid before pursuing other avenues in determining the cause of failure.

Checking the Mailer.Response property returns "File Access Denied". What's wrong?

You probably don't have a Temp path set up, or if you do, the IIS User (or any users authenticating under IIS) don't have read/write access to the temp directory.

Make sure the directory exists
Make sure the Temp var exists in your NT/Win95 environment
Make sure all users which need access to the component (the anonymous IIS user and any other users which authenticate under IIS) have read/write access to this path.

"AspMail never works. I get Server object error 'ASP 0177:800401f3'."

This error means "Invalid class string" -- in other words the call to CreateObject failed because the name object cannot be found by the OLE sub-system. Causes include:

You really didn't run regsvr32 on the server after all.
You ran regsvr32 but it reported an error.
Someone modified security on part of the registry that's preventing the OLE subsystem from reading all or part of the HKEY_CLASSES_ROOT tree.
The name of the object you are trying to create was mispelled or is incorrect.

Determine if it's a permissions problem

Add the anonymous user (used by IIS) to the Administrators group. The test page then worked, proving it was a permissions problem. Do not forget to remove the anonymous IIS user from the Admin group!
Determine if it is a file permissions problem:

After removing the Anonymous user from the Admin group, add failure auditing to the file (smtpsvg.dll), which will determine if the file was ever accessed (by the lack of the failure event). If it isn't, this makes it clear that the failure is prior to file access but go ahead and check file/directory permissions to make sure the anonymous IIS user can access the file.
Check registry permissions

Using Regedt32, do find on smtpsvg.dll. Check the permissions for the key (and sub keys), and make sure that the anonymous user has read rights. Do a find on the class-id, which contains the location value, and version, and check those permissions as well.

"AspMail never works. I get Server object error 80040154."

This is the most common error reported. The error means that ASP could not create the object. Causes include:

You never ran regsvr32 on the DLL. See installation section of this document.
You registered the DLL with regsvr32 in one subdirectory and moved it to another.
IIS does not have proper security permissions to access the DLL or the directory you installed it to. See the ASP FAQ (http://www.signmeup.com/faq/) for information on changing security.
Your server may be running low on memory.
Your evaluation copy has expired. If you purchased the product be sure you followed directions to install your product key.

Note: Some users have reported that restarting the server after registering the DLL was required to use the component. This should not be necessary but reportedly works in a few cases

"AspMail works great but sometimes I get 'Server object error 'ASP 0177:80040154'. What's causing this?"

If AspMail works fine, then it suddenly stops working and ASP begins to report this error, then you've probably got a memory leak under IIS/ASP. What has happened is that AspMail objects can no longer be created. This could be caused by a) You haven't installed the ASP patches that fix known ASP memory leaks b) You have a filter or extension installed that's leaking memory c) You have another component that's leaking memory.

AspMail 2.x has been run under BoundsChecker to verify that AspMail does not leak memory.

"When running regsvr32 I get an error: 'LoadLibrary ("smtpsvg.dll") failed. GetLastError returns 0x0000007e."

You are trying to install the AspMail Intel binary on NT for Alpha. Currently there is no Alpha version of AspMail. One is under construction but there's no ETA for the product yet.
The DLL isn't in the same directory you are running regsvr32 from.
The account you are logged in under doesn't have enough security privileges to read the DLL.
The copy you have is corrupt.

How do I create a line-break in a message?

Under VBScript you can use the predefined constant VbCrLf. Simply using a Chr(13) or a Chr(10) will not work --you must use both. A Carriage-return and line-feed character are required to create a new line in the message. See the sample scripts for examples.

What versions of PGP does AspMail support?

AspMail can support any encryption program that uses command-line parameters. Using PGPPath and PGPParams you can specify input, output and processing options. The current version of PGP (5.0) does not support command-line parameters but the commercial PGP 4.x does as well as the freeware (non-commercial use) PGP 2.6.2.

Can I repeatedly assign values to the BodyText property? and "The message text keeps growing with each email I send."

Yes, the text will be appended to the message. Use ClearBodyText if you need to clear the message text.

Can AspMail be used to retrieve files off the client computer?

AspMail is a server-side component. Retrieving files from the client computer requires a client-side component that has access to the client's local harddisk or a browser that supports file uploads in addition to a server side component/extension that can accept those files. AspMail does not support this function.

How do I get Exchange to route Internet email to the Net?

Exchange uses a service called the Internet Mail Connector (IMC) to allow it to act as an SMTP server and transmit and receive mail via a TCP/IP network. If you are not running the IMC you will not be able to send or receive mail from the Internet by AspMail or any other means.

Once you have SMTP mail going with the IMC, no further action should be necessary to use AspMail. (Thanks to Steve Crane for this information).

Note: You must enable the rerouting on your Exchange's Internet Mail Connector. Go in the properties of your Internet Mail Services (Exchange 5.0). Check the reroute incoming SMTP mail option and add a route to your domain. Mail sent to "yourdomain.com" should be accepted as "inbound". Thanks to S�bastien STORMACQ for this information.

How do I upgrade to the latest version?

Download the latest "eval" version and follow the upgrade directions provided earlier in this document.

Can I redistribute this control with my products?

The license agreement does not permit redistribution of AspMail.

My component is registered. Should the Expires property return a date?

No. Registered versions return N/A for an expiration date. The registration process (per the instructions you received) should be run on the server.

What are the minimum security requirements for AspMail and IIS/ASP?

Technically, the only requirement AspMail has is that it must have access to the temporary directory as noted in one of the previous troubleshooting tips. But IIS and ASP have certain requirements that must be met to run properly. Thanks to Carl Howell for providing this information.

ASP script directory	Creator Owner: Full Control (All)(All) System: "" Admin: "" IUSR: (None)(RX)
\WinNT\	Creator Owner: Full Control (All)(All) System: "" Admin: "" IUSR: (WX)(X)
\WinNT\System32\	System: Full Control (All)(All) Admin: "" IUSR: (RX)(RX)
Inetsrv	System: Full Control (All)(All) Admin: "" Everyone: (RX)(RX)

I'm mailing a large number of people. At some point in the mailing it fails. Can you give me any tips?

The first tip is to use the SMTPLog property to write an SMTP log to disk and see what the point of failure is based on the log. The SMTP server is probably rejecting your message for some reason and the cause is typically determinable from the log.

Secondly, some SMTP servers only accept mail for locally known recipients. The SMTP server may be rejecting your message since it is being addressed to recipients outside the domain of that SMTP server. This is unusual but could possibly be the problem you are running into.

What are some of the issues that affect the speed of the mailing?

A small message should take 3-4 seconds to send if the server is local and all other conditions are normal. The following list are some items that can affect transfer speed.

The slower the TCP connection the longer the mailing will take. Typically a local server is much faster than a remote server. If you are losing packets between your server and the SMTP server you can expect longer times due to this packet loss.
The size of the mailing. The larger the message the longer the message transfer will take to send.
CPU utilization: If your CPU is experiencing heavy usage you can expect it to take longer to transfer mail.
SMTP server utilization: If your SMTP server is experiencing heavy traffic response times from the server are going to take longer thus increasing the time it takes to send a message.

Does the 2 CPU license cover two servers or two processors?

In accordance with the license agreement, the 2 CPU license would cover either 2 single CPU servers or 1 dual CPU server. With this pricing model, AspMail is far more inexpensive than any "competing" products.

Technical Support

If you require technical support please send complete details about the problem you are having to support@serverobjects.com. Include the version of AspMail you are using, any error messages, sample code snippets that demonstrate the problem (most problems are scripting errors), information about the hosting environment etc. For example, if you are using ASP to host the component please let me know what version of IIS and ASP you are running (and if you have installed any of the HotFixes). The more information you can provide in your request for help, the faster your problems can be resolved.

Property	Description
BodyText	The message body text. To clear the text once you have set it use the ClearBodyText Method. Example: Mailer.BodyText = "Your order for 15 widgets has been processed"
CharSet	The character set. By default the char set is US Ascii Valid values: 1 = US Ascii 2 = ISO-8859-1 Example: Mailer.CharSet = 2
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. Example: Mailer.ConfirmRead = true
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 messages'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. Example: Mailer.ContentType = "text/html"
CustomCharSet	If you wish to use a character set besides the included types you can set CustomCharSet to a character set string. Example: Mailer.CustomCharSet = "ISO-2022" or Mailer.CustomCharSet = "big5"
DateTime	AspMail 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. Example: Mailer.DateTime = "Fri, 02 May 1997 10:53:49 -0500"
Encoding	The encoding type for attachments. The default setting is MIME. Valid values: 1 = UUEncoded 2 = MIME Example: Mailer.Encoding = 1
Expires	If the component is an eval version the expires property will return the date that the component quits functioning. Example: Response.Write "Component Expires: " & Mailer.Expires
FromName	The message originator’s name. Example: Mailer.FromName = "Joe’s Widget Shop"
FromAddress	The message originator’s email address. Example: Mailer.FromAddress = "joe@widgets.com"
Live	Live allows you to test the component without an SMTP server. If Live is set to false then the NET SEND message will be executed with the FromName property being used as the recipient of the message. Only the subject is sent to the recipient. Example: Mailer.FromName = "ASPProgrammer" Mailer.Live = false
PGPPath	The path where PGP is located.
PGPParams	Parameters that PGP will use to process message.
Priority	Sets the message priority. Priorities are 1-5 and are reflected in the X-Priority Valid values: 1 – High 3 – Normal 5 – Low Example: Mailer.Priority = 1
RemoteHost	For Sierra Web Design set the Mailer.RemoteHost as follows: Mailer.RemoteHost = "127.0.0.1" 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, seperated by a semicolon. If the primary server is down the component will attempt to send the mail using the seconary server and so on. Example: Mailer.RemoteHost = "mailhost.myisp.net" or Mailer.RemoteHost = "mailhost.myisp.net; mailhost.myotherisp.net"
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. Example: Mailer.ReturnReceipt = false
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! Example: Mailer.SMTPLog = "c:\smtplog.txt"
Subject	The message subject. Example: Mailer.Subject = "Stock split announced!"
SuppressMsgBody	The SuppressMsgBody property is true by default and is used in conjuction 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 AspMail should wait for a response from the remote server. The default is 30 seconds. Example: Mailer.Timeout = 15
Urgent	The urgent flag sets the X-Urgent header in the outgoing message. Not all mail readers support this flag. Example: Mailer.Urgent = true
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 Example: Mailer.UseMSMailHeaders = false
Version	Gets the internal component version number. Example: Response.Write "Component Version: " & Mailer.Version
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 Example: if Mailer.SendMail then Response.Write "Mail sent..." else Response.Write "Mail failure. Check mail host server name and tcp/ip connection..." end if	The SendMail method attempts to send the email.
AddRecipient	Mailer.AddRecipient "Steve Genusa", "steve@genusa.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	Mailer.AddCC "Jay Jones", "jayj@somehost.net"	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	Mailer.AddBCC "Jay Jones", "jayj@somehost.net"	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. Example: Mailer.AddAttachment "p:\shipping\proddsk1.zip"	True or False	Adds attachments to current mailing. Make sure that the IUSR_XYZ IIS user, or the authenticated user has security rights that allow the component to read the necessary files! Note: Attachments are not supported in the eval version
ClearAttachments	None	None	Clears any attachments that were previously set. Example: Mailer.ClearAttachments
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 Example: Mailer.AddExtraHeader ("X-HeaderName: XHdrValue")	True or false. Returns true if X-Header was added.	Adds extra X-Headers to the mail envelope.
GetBodyTextFromFile	See pgpmail.asp for more information.	See pgpmail.asp for more information.	Loads message's body text from a file. Optionally runs PGP on the message text. See pgpmail.asp for more information.

About AspMail

Changes in AspMail 2.0