AspEmail 4.5 Manual

Copyright (c) 1999 - 2001 Persits Software, Inc.
All Rights Reserved

What is AspEmail

AspEmail 4.5 is an active server component for sending email messages using an external SMTP server in an ASP or VB environment. AspEmail 4.5 supports multiple recipients, multiple CC, multiple Bcc, multiple file attachments, HTML format, embedded images, and non-US ASCII character sets. AspEmail 4.5 is free except for the image embedding functionality, Quoted-Printable encoding, multipart/alternative support, and message queuing described below.

A free copy of AspEmail can be downloaded from www.aspemail.com/download.html.

• multipart/alternative support. You can now send messages in both text and HTML formats at the same time to support email clients that are not HTML-enabled. Set the HTML version of your message body via the Mail.Body property, and text version via Mail.AltBody (premium feature).
• NNTP authorization. Authentication support via the Username/Password properties has been extended to the method SendToNewsgroup which enables you to post articles to password-protected news servers. .
• Mail.Timeout property added which specifies socket timeout.

General Requirements

Windows 95/98 or Windows NT 4.0/2000, and
An external SMTP server.

Specific Requirements

Internet Information Server 3.0, 4.0 or 5.0 and Active Server Pages, or
Personal Web Server (any version) and Active Server Pages, or
Visual Basic, Visual C++, or any other development environment supporting COM components.

Getting Started

The setup program AspEmail.exe automatically registers AspEmail.dll on your system. To register AspEmail on another machine, move the file aspemail.dll to that machine and execute the following command at your MS DOS or Start/Run prompt:

C:\>regsvr32 c:\AspEmailDir\AspEmail.dll

AspEmail is shipped with an evaluation version of the AspUpload component from Persits Software, Inc. which can be used to upload file attachments to the server as discussed below. Register AspUpload by executing the following command:

C:\>regsvr32 c:\TargetDir\Bin\AspUpload.dll

AspUpload is not needed to run AspEmail. However, the sample ASP application SendMail shipped with AspEmail makes use of it to demonstrate the attachment functionality of AspEmail, so it is a good idea to register it too, unless it has already been registered on your system. For more information on the AspUpload component, visit www.aspupload.com.

Using AspEmail

To use AspEmail in an ASP environment, you must create an instance of the AspEmail object in your ASP script as follows:

<%
...
Set Mail = Server.CreateObject("Persits.MailSender")
...
%>

To use AspEmail in a VB environment, open a VB project, go to Project/References... and check the box next to Persits Software AspEmail 4.4. Declare an AspEmail object variable as follows:

Dim Mail As MailSender

Create an instance of the AspEmail object as follows:

Set Mail = New MailSender

To send email messages, AspEmail "talks" to an SMTP server. You must specify the SMTP host address and, optionally, port number as follows:

Mail.Host = "smtp.mycompany.com"
Mail.Port = 25 ' Optional. Port is 25 by default

Starting with AspEmail 4.3, you can specify a comma- or semicolon-separated list of SMTP hosts, as follows:

Mail.Host = "smtp.mycompany.com;smtp2.mycompany.com;host.someothercompany.com"

If the first host on the list is down, AspEmail will automatically attempt to connect to the second host, etc. If none of the specified hosts are working an error exception will be thrown.

You must also specify the sender's email address and, optionally, name as follows:

Mail.From = "sales@mycompany.com"
Mail.FromName = "Sales Department" ' Optional

To add the message recipients, CCs, BCCs, and Reply-To's, use the AddAddress, AddCC, AddBcc and AddReplyTo methods, respectively. These methods accept two parameters: the email address and, optionally, name. Notice that you must not use an '=' sign to pass values to the methods. For example,

Mail.AddAddress "jsmith@company1.com", "John Smith"
Mail.AddCC "bjohnson@company2.com" ' Name is optional

Use the Subject and Body properties to specify the message subject and body text, respectively. A body can be in a text or HTML format. In the latter case, you must also set the IsHTML property to True. For example,

Mail.Subject = "Sales Receipt"
Mail.Body = "Dear John:" & chr(13) & chr(10) & "Thank you for your business. Here is your receipt."

or

Mail.Subject = "Sales Receipt"
Mail.Body = "<HTML><BODY BGCOLOR=#0000FF>Dear John:....</BODY></HTML>"
Mail.IsHTML = True

To send a file attachment with the message, use the AddAttachment method. It accepts the full path to the file being attached. Call this method as many times as you have attachments. Notice that you must not use the '=' sign to pass a value to the method:

Mail.AddAttachment "c:\dir\receipt.doc"

To send a message, call the Send method. The method throws exceptions in case of an error. You may choose to handle them by using the On Error Resume Next statement, as follows:

On Error Resume Next
Mail.Send
If Err <> 0 Then
    Response.Write "An error occurred: " & Err.Description
End If

If the machine running IIS and AspEmail is separated from your SMTP host by Microsoft Proxy Server, you may experience problems connecting to the SMTP server. AspEmail would report the error "Host not found" although you as an interactive logged-in user would have no problems connecting to the same SMTP server with your email client software.

To resolve the connection problem you must assign NT user credentials to the IIS Admin service using the CREDTOOL command-line utility which can be found in the directory \MSP\Clients\I386 on the Proxy Server machine. Copy this utility to the machine running IIS and execute the following command at your MS DOS prompt (specify your own user credentials):

credtool -w -n inetinfo -c <username> <domain> <password>

This command assigns the credentials of a specified NT user to the executable inetinfo.exe that hosts the IIS Admin service. Once this is done, you need to configure your IIS to recognize the credentials. Create the file Wspcfg.ini and place it in the directory where inetinfo.exe is located (usually, it is c:\winnt\system32\inetsrv). Put the following text in the Wspcfg.ini file:

[Inetinfo]
ForceCredentials=1

After that, restart IIS by executing the commands:

net stop iisadmin /y
net start w3svc

AspEmail is capable of generating encrypted and/or signed mail in the industry-standard S/MIME format. To send secure mail, AspEmail must be used in conjunction with the AspEncrypt cryptographic component from Persits Software, Inc. For more information on how to send secure mail using the AspEmail and AspEncrypt components, and to download your free trial copy of AspEncrypt, visit the web site www.aspencrypt.com.

AspEmail is free when you use basic functionality described above. AspEmail also offers premium features that require a registration key after a 30-day evaluation period. To purchase a key, visit www.aspemail.com.

AspEmail 4.2 has a new method, SendToQueue, which does not attempt to send a message directly to the SMTP server. Instead, the message is placed in a queue from where it is later retrieved and sent out by the EmailAgent NT service, a background process. Your mail-sending ASP script no longer has to wait until a message is sent, which means a better client-response time. The EmailAgent service itself is free and can be downloaded from www.aspemail.com/download.html. The SendToQueue is a premium feature and requires a registration key after a 30-day evaluation period. To learn how to use AspEmail and EmailAgent, see the EmailAgent manual at the AspEmail.com web site.

Starting with version 4.5, AspEmail is capable of sending messages in both text and HTML formats to support email clients that are not HTML-enabled. The HTML version of a message is specified the regular way, via the Body property. The alternative text version of the message is specified via the new property AltBody, as follows:

Mail.Body = "<HTML><BODY>Dear John:<P>...</BODY></HTML>"
Mail.AltBody = "Dear John:..."

Note that setting the property AltBody has a side effect: the property IsHTML automatically gets set to True.

AspEmail can send email messages with embedded images. The following example uses the file margin.gif (included with the component) as the background image for a message:

...
Mail.Body="<HTML><BODY BACKGROUND=""cid:My-Image"">...</HTML>"
Mail.AddEmbeddedImage "c:\aspemaildir\margin.gif", "My-Image"

The method AddEmbeddedImage takes two parameters: the full path to an image file and a Content ID which is simply a string without spaces which your body HTML references as follows:

"cid:ContentID"

In the example above we use the Content ID "My-Image" which is referenced by the BACKGROUND attribute of a <BODY> tag. We can use the same technique to embed an image inside the message body using an <IMG> tag:

Mail.Body = "<HTML>....<IMG SRC=""cid:My-Company-Logo"">...</HTML>"
Mail.AddEmbeddedImage "c:\aspemaildir\logo.gif", "My-Company-Logo"

In a similar manner, you can embed a sound file in your message using the <BGSOUND> tag, for example:

Mail.Body = "<HTML><BGSOUND=""cid:My-Sound""></BGSOUND>...</HTML>"
Mail.AddEmbeddedImage "c:\winnt\media\ringin.wav", "My-Sound"

Note: Content-IDs are case-sensitive. Make sure the values specified by "cid:..." and AddEmbeddedImage fully match.

To make your script more readable, you may choose to place your message body in a separate file and import it into the Body property using the method AppendBodyFromFile which accepts the full path to a text ot HTML file containing the message body. For example, your HTML file may look like this:
 

<!-- File messagebody.html--> <HTML> <HEAD> <STYLE>BODY {  COLOR: #427d64; FONT-FAMILY: "Arial"; FONT-SIZE: 12pt; MARGIN-LEFT: 8em } </STYLE> </HEAD> <BODY BACKGROUND="cid:My-Background-Image"> <H2>Thank you for Shopping At Our Online Store!</H2> .... </BODY> </HTML>

To use this file as a message body, use the following code:

Mail.AppendBodyFromFile "c:\aspemaildir\messagebody.html"
Mail.AddEmbeddedImage "c:\aspemaildir\margin.gif", "My-Background-Image"

The AppendBodyFromFile method can be used instead of, or in conjunction with, the Body property.

SMTP servers sometimes require email clients to supply a username and password to be able to send mail. This is usually done to prevent "spammers" from using the server to send out unsolicited mail. The most commonly used authentication method is called AUTH LOGIN and described in RFC 2554. AspEmail 4.3 provides support for the AUTH LOGIN authentication via the properties Username and Password. Use these properties as follows:

Mail.Username = "myusername"
Mail.Password = "mypassword"

Starting with AspEmail 4.5, you can also use these properties to post articles to password-protected news servers via the SendToNewsgroup method.

AspEmail is capable of sending messages in alphabets other than US-ASCII by supporting the "Quoted-Printable" format. This format is described in RFC-2045. The idea of the format is that characters less than 33 and greater than 126 are represented by an "=" followed by a two digit hexadecimal representation of the character's value. For example, the decimal value 12 (US-ASCII form feed) is represented by "=0C", and the decimal value 61 (US-ASCII "=") can be represented by "=3D".

AspEmail encodes the message body in the Quoted-Printable format automatically if the ContentTransferEncoding property is set to "quoted-printable". You may also set the CharSet property to the appropriate character set.

The following code snippet sends a message in Russian in the KOI8 standard from a text file (not shown here):
...
Mail.ContentTransferEncoding = "quoted-printable"
Mail.Charset = "koi8-r"
Mail.AppendBodyFromFile "c:\russiandoc.txt"
Mail.Send

If you wish to send a message with certain mail headers such as Subject:, To: or From: containing non-US-ASCII characters, you should use the method Mail.EncodeHeader to encode your character string according to the RFC 1522. For example:
...
Mail.Subject = Mail.EncodeHeader("La fête à Jean-Sébastien Bach")
Mail.FromName = Mail.EncodeHeader("José Bové")
Mail.AddAddress "oystein@somecompany.no", Mail.EncodeHeader("Øystein")

Premium Feature: Support for Network News Transfer Protocol (NNTP) 

AspEmail 4.4 allows you to programmatically post messages (articles) to network newsgroups. The following code fragment posts a short message to the newsgroup microsoft.test at the news server msnews.microsoft.com:

Set Mail = Server.CreateObject("Persits.MailSender")
Mail.Host = "msnews.microsoft.com"
Mail.From = "me@mycompany.com"
Mail.Subject = "Just a test"
Mail.Body = "Hello microsoft.test newsgroup!"
Mail.SendToNewsgroup "microsoft.test"

AspEmail is shipped with a sample ASP application that allows you to create and send email messages with attachments over the Web. The application consists of the following files:

global.asa (collection object creation)
SendMail.asp (main Email interface page)
Attachments.asp (attachment handling page)
UploadScript.asp (upload script which uses AspUpload).

To upload file attachments from a client machine to the server where the script is running, the application uses a trial version of AspUpload, a powerful file upload component from Persits Software. The file AspUpload.dll is shipped with AspEmail and must be registered on your system for the sample application to function. For complete documentation on the AspUpload component, or to purchase AspUpload, visit http://www.AspUpload.com.

AspEmail Properties

Property and Type	Comments
Host As String	Required. The internet address of a SMTP host to be used to send messages.
Port As Integer	The SMTP port number. 25 by default.
From As String	Required. The sender's email address.
FromName As String	The sender's name.
Subject As String	Message subject.
Body As String	Message body. Can be in a text or HTML format. In the latter case, the IsHTML property must be set to True.
IsHTML As Boolean	False by default. If set to True, AspEmail will set the Content-Type of the message body to text/html.
Priority As Integer	Message priority. Valid values are 1 (high), 3 (normal) and 5 (low). 0 by default which means priority is not specified.
Helo As String	"AspEmail" by default. This string is sent with the HELO command when an SMTP session begins. Used by an SMTP client to identify its domain name to the SMTP server.
ContentTransferEncoding As String	"7bit" by default. Specifies the Content-Transfer-Encoding MIME header for the message body. Other valid values include "8bit" and "quoted-printable". If you set this property to "quoted-printable" AspEmail will automatically convert the message body to the Quoted-Printable format as specified in RFC-2045.  This is a premium feature.
CharSet As String	"ISO-8859-1" by default. Specifies the charset component of the Content-Type MIME header. This is a premium feature.
Timestamp  As Date	Used for deferred message processing. Specifies when the message is to be sent out by EmailAgent. This property is only used with the SendToQueue method and ignored by the Send method. For more information, see the EmailAgent manual at www.aspemail.com, section "Deferred Message Processing."
Username As String	Used for AUTH LOGIN authentication together with Password. Use the Username/Password properties if your SMTP server requires a mail client to supply authentication parameters. This is a premium feature.
Password As String	See comments to Username above. This is a premium feature.
Timeout As Long	Specifies socket timeout (in millisecond)
AltBody As String	Specifies an alternative text version of a message while Body specifies an HTML version. When this property is set, AspEmail generates a "multipart/alternative" message to support email clients that are not HTML-enabled. Side effect: when this property is set, IsHTML property gets set to True. This is a premium feature.
Expires As Date (read-only)	Returns the expiration date of the component's premium features. Returns 9/9/9999 if a valid registration key is installed. Returns 0 (displayed as "12:00 AM") if expiration value in the registry is corrupt or missing.

AspEmail Methods

Method Name	Arguments	Comments
AddAddress	Email As String Optional Name = ""	Adds an email address and optionally the corresponding full name to the letter's To: list.
AddCC	Email As String Optional Name = ""	Adds an email address and optionally the corresponding full name to the letter's Cc: list.
AddBcc	Email As String Optional Name = ""	Adds an email address and optionally the corresponding full name to the letter's Bcc: list.
AddReplyTo	Email As String Optional Name = ""	Adds an email address and optionally the corresponding full name to the letter's Reply-To: list.
AddAttachment	Path As String	Adds a file to the list of file attachments to be sent with the message.
AddCustomHeader	Header As String	Adds a custom header to the message, e.g. mail.AddCustomHeader "Return-Receipt-To: <name@domain.com>"
AddEmbededImage	Path As String ContentID As String	Adds an image file to the list of images embedded in the message body. ContentID is a string without spaces, such as "My-Image", which will be referenced by the body HTML in the following way: <IMG SRC="cid:My-Image"> or <BODY BACKGROUND="cid:My-Image"> This is a premium feature.
AppendBodyFromFile	Path As String	Appends the Body property from a text or HTML file specified by Path. This is a premium feature.
Send	N/A	Sends the message. Throws exceptions in case of an error. See the section Error Codes below for the list of error codes.
SendToQueue	Optional Path = ""	Sends a message to the message queue and returns immediately. Requires the EmailAgent service to be running. Path specifies the path to a message queue where the message is to be posted. If Path is omitted, EmailAgent's Message Queue Path configuration parameter in the registry will be used. For more information on EmailAgent, and to download a free copy, visit www.aspemail.com. This is a premium feature.
SendEncrypted	Msg As CryptoMessage	Sends an encrypted message. Msg is an object creatable by the AspEncrypt component. See AspEncrypt Web site for more information.
SendSigned	Msg As CryptoMessage	Sends a digitally signed message. See AspEncrypt Web site for more information.
SendSignedAndEncrypted	Msg1 As CryptoMessage, Msg2 As CryptoMessage	Sends a message which is first digitally signed and then encrypted. See AspEncrypt Web site for more information.
SendToNewsgroup	Newsgroup As String	Posts a message (article) to a news group specified by Newsgroup. This method ignores addresses specified by AddAddress, etc. methods. Host must point to a valid NNTP server. Uses port 119 unless the Port property is set to anything other than the default (25), in which case it uses a value specified by Port.This is a premium feature.
Reset	N/A	Clears all address and attachment lists so that a new message can be sent.
ResetAll	N/A	Same as Reset plus resets all properties to their respective default values.
EncodeHeader	Header as String Returns: String	Encodes a string containing non-US-ASCII characters according to RFC 1522. Use this method to encode a non-US-ASCII subject, sender's name or recipient's name, e.g. Mail.Subject = Mail.EncodeHeader("La fête à Jean-Sébastien Bach") or Mail.AddAddress "oystein@somecompany.no", Mail.EncodeHeader("Øystein")
LogonUser	Domain As String; UserID As String; Password As String.	Impersonates the specified user account. If Domain is empty the local computer will be used to validate the UserID/Password. The caller must have the "Act as Part of the Operating System" privilege, otherwise the error "Privilege is not held by client" error will be thrown. This method is useful when using the SendToQueue method if the message queue is located on another machine and the current user account's credentials are insufficient to place a message in a remote queue.
RevertToSelf	N/A	Ends impersonatio begun by LogonUser.

Note: the following error codes are generated by AspEmail's properties and methods and can be obtained via the built-in Err object when the On Error Resume Next statement is used.

Name	Decimal	Hex
WINSOCK_INITFAILED	1	800A0001
GETHOSTBYNAME	2	800A0002
CREATESOCKETFAILED	3	800A0003
CONNECTFAILED	4	800A0004
SENDFAILED	5	800A0005
FROM_SMTPSERVER	6	800A0006
OPENFILE	7	800A0007
NOTENOUGH_MEMORY	8	800A0008
FILEREAD_FAILED	9	800A0009
HOST_NONSPECIFIED	10	800A000A
CONTENTIDEMPTY	11	800A000B
CONTENTIDNOTUNIQUE	12	800A000C
INVALIDPRIORITY	13	800A000D
EXPIRATION	14	800A000E
CRYPTOMESSAGEEXPECTED	15	800A000F
PATHNOTFOUNDFORQ	16	800A0010
OPENNEWFILE	17	800A0011
CREATESTG	18	800A0012
CREATESTG2	19	800A0013
CREATESTREAM	20	800A0014
LOGONUSERFAILED	21	800A0015
HEADERTOOLONG	23	800A0017
HEADERTOOLONG2	24	800A0018
RECVFAILED	25	800A0019