|
AspEmail 4.5.0.2
Manual
Copyright (c) 1999 - 2002 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. What's New in Version 4.5.0.2
(Service Release)
- Mail.MailFrom property added. In earlier versions, both the
From: and Return-Path: headers were set to
the Mail.From value. For bounced-mail handling purposes, it may be
useful to set the Return-Path: header to an email
address other than the sender's address, and that's what the MailFrom
property does.
- An optional AddToBody flag added to the
AppendBodyFromFile method to specify whether the Body or
AltBody property should be appended. In earlier versions, only
Body could be appended via this method but not AltBody.
- For better compliance with the SMTP protocol, AspEmail 4.5.0.2
issues the command EHLO instead of HELO whenever the
Username property is used.
What's New in Version
4.5
- 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.
System Requirements
General Requirements
Windows 95/98 or Windows NT 4.0/2000/XP, and An
external or local 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 http://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 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
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 http://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 http://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: Multipart/alternative Support (New in AspEmail 4.5)
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.
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-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. Premium Feature: AUTH LOGIN
Authentication (Enhanced in AspEmail
4.5)
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. 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
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"
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/. Technical
Support
If you are having problems with
AspEmail, check with our searchable database of technical articles at SUPPORT.PERSITS.COM. If
none of the articles helped rectify your problems, write us at support@aspemail.com.
Object Reference
AspEmail Properties
Property and
Type |
Comments |
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. |
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. |
CharSet As
String |
"ISO-8859-1" by default. Specifies the charset
component of the Content-Type MIME header. This is a premium feature. |
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. |
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. |
From As
String |
Required. The sender's email
address. |
FromName As
String |
The sender's name. |
Helo As
String |
"AspEmail" by default. This string is sent with
the HELO command (or EHLO if Username property is
set) when an SMTP session begins. Used by an SMTP client to
identify its domain name to the SMTP server. |
Host As
String |
Required. The internet address of a SMTP host to
be used to send messages. |
IsHTML As
Boolean |
False by default. If set to True, AspEmail will
set the Content-Type of the message body to
text/html. |
MailFrom As String |
Sets an email address for the
Return-Path: header. Useful for bounced-mail
handling purposes. If this property is not specified, the
Mail.From value is used for this header. |
Password As String |
See comments to Username above. This is a premium feature. |
Port As
Integer |
The SMTP port number. 25 by
default. |
Priority As
Integer |
Message priority. Valid values are 1 (high), 3
(normal) and 5 (low). 0 by default which means priority is not
specified. |
Subject As
String |
Message subject. |
Timeout As Long |
Specifies socket timeout (in
millisecond) |
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 http://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. |
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. |
AddAttachment |
Path As String |
Adds a file to the list of file attachments to
be sent with the message. |
AddBcc |
Email As String Optional Name = "" |
Adds an email address and optionally the
corresponding full name to the letter's Bcc:
list. |
AddCC |
Email As String Optional Name = "" |
Adds an email address and optionally the
corresponding full name to the letter's Cc:
list. |
AddCustomHeader |
Header As String |
Adds a custom header to the message,
e.g.
mail.AddCustomHeader "Return-Receipt-To:
<name@domain.com>" |
AddEmbeddedImage |
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. |
AddReplyTo |
Email As String Optional Name = "" |
Adds an email address and optionally the
corresponding full name to the letter's Reply-To:
list. |
AppendBodyFromFile |
Path As String Optional AddToBody =
True |
Appends the Body property from a text or
HTML file specified by Path (if the AddToBody flag
is set to True or omitted.) If AddToBody is set to False,
the content of the file is appended to AltBody instead.
This is a premium
feature. |
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. |
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. |
RevertToSelf |
N/A |
Ends impersonatio begun by
LogonUser. |
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. |
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. |
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 http://www.aspemail.com/.
This is a premium
feature. |
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. | Error Codes
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 | |