AspEmail 4.4 Manual

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

What is AspEmail 4.4?

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

This implemenation of AspEmail does not support the premium features described below.

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
Using AspEmail with Microsoft Proxy Server
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
S/MIME-based Encryption and Digital Signature Support
Starting with Build 4.0.0.3, 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.
Premium Feature: Support for Message Queuing
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.
Premium Feature: Sending Messages with Embedded Images and Sounds
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"
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:


<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 AUTH LOGIN Authentication (new in AspEmail 4.3)
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.
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
Support for non-US-ASCII Characters in Message Headers (new in AspEmail 4.3)
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) (new in AspEmail 4.4)
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"
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.

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.

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.

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)

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

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.

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)