AspEmail 4.0 Manual

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


What is AspEmail 4.0

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

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

System Requirements
General Requirements
Windows 95/98 or Windows NT 4.0+, and
An external SMTP server.
Specific Requirements
Internet Information Server 3.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

To register AspEmail on your system, 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:\AspEmailDir\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.0. 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

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


Premium Feature: Sending Messages with Embedded Images

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 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-Background-Image"">...</BODY></HTML>"
Mail.AddEmbeddedImage "c:\aspemaildir\margin.gif", "My-Background-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:<Content ID>"

In the example above we use the Content ID "My-Background-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"

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.

Premium Feature: Support for Alphabets Other Than US-ASCII
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


Sample ASP Application

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.

Object Reference
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.
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.
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.
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.
Error Codes
 
Error Code Description
1 Winsock initialization failed.
2 gethostbyname failed.
3 Socket creation failed.
4 Connection failed.
5 Sending data failed.
6 Error returned from SMTP server
7 Opening file failed.
8 Not enough memory.
9 Reading from file failed.
10 Host not specified
11 ContentID may not be empty (generated by AddEmbededImage)
12 ContetnID must be unique (generated by AddEmbeddedImage)
13 Invalid Priority value (generated by put_Priority)
14 Component is expired or invalid registration key (generated by premium methods and properties only)