AspEmail Object Reference

MailSender Member List

MailLogger Member List

LogEntry Member List

MailSender Properties


AltBody As String (Read/Write)
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 (Read/Write)
Specifies a 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 (Read/Write)
"ISO-8859-1" by default. Specifies the charset part of the Content-Type MIME header. Setting this property to a non-default value causes AspEmail to perform a conversion of message body characters into the specified character set. If this property it set to "UTF-8", AspEmail uses the UTF-8 encoding. To learn more, and for a list of valid values for this property, see Chapter 6. This is a premium feature.

ContentTransferEncoding As String (Read/Write)
"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. You should always set this property to "quoted-printable" if you set CharSet to "UTF-8". 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 the expiration value in the registry is corrupt or missing.

From As String (Read/Write)
Specifies the sender's email address. This property is required.

FromName As String (Read/Write)
Specifies the sender's name.

Helo As String (Read/Write)
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. By default, AspEmail uses a value returned by the GetComputerNameEx Win32 API.

Host As String (Read/Write)
The internet address of an SMTP host to be used to send email. This property is required, unless message queuing is used and a host is specified via the EmailAgent configuration panel.

IsHTML As Boolean (Read/Write)
False by default. Must be set to True if the body is in the HTML format.

MailFrom As String (Read/Write)
Specifies an email address for the Return-Path: header. Useful for bounced-mail handling purposes. If this property is not specified, the From value is used for this header.

Password As String (Read/Write)
See comments to the property Username. This is a premium feature.

Port As Integer (Read/Write)
Specifies the SMTP port number. 25 by default.

Priority As Integer (Read/Write)
Specifies message priority. Valid values are 1 (high), 3 (normal) and 5 (low). 0 by default which means priority is not specified.

Queue As Boolean (Read/Write)
Enables message queuing. False by default. If set to True, specifies that a subsequent call to Send will place the message in a message queue to be processed by EmailAgent. This is a premium feature.

QueueFileName As String (Read/Write)
Returns the name of a message file generated by a call to Mail.Queue = True followed by Mail.Send. Do NOT use this property to specify a file attachments, use the AddAttachment method instead.

RegKey As String (Write-only)
Specifies the registration key. If this property is not set, AspEmail will look for a registration key in the system registry under HKLM\Software\Persits Software\AspEmail\RegKey.

SSL As Boolean (Read/Write)
Enables the Secure Socket Layer (SSL) protocol. If set to True, the Port property must also be set to 465. This property was added in Version 5.4. This is a premium feature.

Subject As String (Read/Write)
Specifies the message subject.

Timeout As Integer (Read/Write)
Specifies socket timeout (in millisecond).

Timestamp As Date (Read/Write)
Used for deferred message processing. Specifies when the message is to be sent out from the queue by EmailAgent. This property is only used when Queue is set to True, and ignored when it is False.

TLS As Boolean (Read/Write)
Enables the Transport Layer Security (TLS) protocol. Should be set to True when the SMTP server pointed to by Mail.Host requires TLS. This property was added in Version 5.1. This is a premium feature.

TLSVersion As String (Read/Write)
Specifies the version of the TLS protocol. "1.2" by default. Set this property to "1.0" to force AspEmail to use TLS 1.0. This property was added in Version 5.5.

Username As String (Read/Write)
Used for SMTP authentication together with Password. Use the Username/Password properties if your SMTP server requires a mail client to supply authentication parameters. AspEmail supports AUTH=LOGIN, CRAM-MD5 and NTLM authentication methods. This is a premium feature.

Version As String (Read-only)
Returns a string representing the current component version, e.g. "5.6.0.0".

MailSender Methods


Sub AddAddress(Address As String, Optional Name = "")
Adds an email address and optionally the corresponding full name to the message's To: list. This method can be called multiple times per message.

Sub AddAltBody(Body As String, ContentType As String)

Adds a multipart/alternative version of the body to the message. This method is useful for generating email messages with advanced content, such as accelerated mobile pages (AMP), calendar invitations, etc.

Body specifies the content of the body subsection.

ContentType specifies the content-type header for this subsection of the message body, such as "text/html", "text/calendar", etc.

This method was introduced in Version 5.6. See Section 2.5 - Extended Multipart/Alternative Support for more information.

This is a premium feature.


Sub AddAttachment(Path As String)
Adds a file to the list of file attachments to be sent with the message. A full physical path must be specified. This method can be called multiple times per message.

Sub AddAttachmentMem(Name As String, Blob As Variant)
Attaches a memory file. Name specifies the file name, Blob is a memory binary array. A typical 2nd argument would be a recordset value containing a file blob, or an expression such as File.Binary where File is an AspUpload file object. See Chapter 3 for more info.

Sub AddBcc(Address As String, Optional Name = "")
Adds an email address to the message's BCC: (blind carbon copy) list. This method can be called multiple times per message.

Sub AddCC(Address As String, Optional Name = "")
Adds an email address and optionally the corresponding full name to the message's CC: (carbon copy) list. This method can be called multiple times per message.

Sub AddCustomHeader(Header As String)

Adds a custom header to the message, e.g. mail.AddCustomHeader "Return-Receipt-To: <name@domain.com>"

Starting with Version 5.0.0.5, you can use this method to specify a custom Message ID for your message, e.g.

Mail.AddCustomHeader "Message-ID: abc12356"


Sub 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">. See Chapter 4 for more info. This is a premium feature

Sub AddEmbeddedImageMem(Name As String, ContentID As String, Blob As Variant)
Same as AddEmbeddedImage but adds an image from memory rather than disk. This is a premium feature.

Sub AddReplyTo(Address As String, Optional Name)
Adds an email address and optionally the corresponding full name to the message's Reply-To: list. This method can be called multiple times per message.

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

Starting with Version 5.0.0.5, this method supports text files in Unicode format (both little-endian and big-endian.)

As of Version 5.6, this method can be used to append to an arbitrary multipart/alternative sub-section of the message body by setting AddToBody to a string content-type value, such as "text/html", "text/plain", "text/calendar", etc.

This is a premium feature.


Function EncodeHeader(Header As String, Optional Charset = "ISO-8859-1") As String

Encodes a string containing non-US-ASCII characters according to RFC-1522, returns the resultant encoded string. 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")

Charset can be set to "UTF-8" or any valid character set code described in Chapter 6.


Function GetAccessToken(Service As String, Code As String, Refresh As Boolean) As MailSender

Obtains the oAuth access token, refresh token (if applicable) and expiration information from an oAuth authorization code or previously obtained refresh token. Returns a new instance of the MailSender object with the Username property set to the access token, Password to refresh token, and Timeout to expiration information in seconds.

Service specifies the name of the oAuth service. Currently, the only supported service is "GMAIL".

Code specifies either the oAuth authorization code, or previously obtained refresh token.

Refresh is a flag indicating what value Code represents: an authorization code (if set to True) or refresh token (if set to False).

This method was introduced in version 5.5.0.1.

For more information, see Section 5.6 - Google GMAIL oAuth Support.


Function GetAltBody(ContentType As String) As String

Retrieves a specific multipart/alternative version of the message body identified by its content type. This method can be used in conjunction with AddAltBody.

ContentType specifies the content-type of the body sub-section to be retrieved. Can be set to "text/plain", "text/calendar", etc.

This method was introduced in Version 5.6. See Section 2.5 - Extended Multipart/Alternative Support for more information.


Sub LogonUser(Domain As String, Username As String, Password As String, Optional Flag = 2)

Impersonates the specified user account. If Domain is empty, the local computer will be used to validate the Username/Password. The caller must have the "Act as Part of the Operating System" privilege, otherwise the error "A required privilege is not held by client" error will be thrown.

This method is useful when using message queuing (Mail.Queue = True) 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.

The Flags argument should not normally be used.


Sub Reset()
Clears all address, attachment and custom header lists so that a new message can be sent.

Sub ResetAddresses()

Clears all address lists so that a new message can be sent. Does not clear attachments, embedded images, custom headers or properties.

Introduced in Version 5.2.


Sub ResetAll()
Same as Reset plus resets all properties to their respective default values.

Sub RevertToSelf()
Ends impersonation begun by LogonUser.

Function Send(Optional Path = "") As Boolean
Sends a message. Returns True if successful, False otherwise. Throws exceptions in case of an error. If Mail.Queue is set to True, the message is not sent directly to the SMTP server but placed in the message queue for further processing by EmailAgent. The name of the message file thus created can be retrieved via the property QueueFileName. Path specifies the message queue location. If this argument is omitted, the default message queue location is used. In case message queuing is not used, Path is ignored.

Sub SendCertified(Cert As CryptoCert, Domain As String, Selector As String, Options As Long, Optional Path = "")

Sends a message equipped with a DKIM signature.

  • Cert is the signer certificate creatable by the AspEncrypt component.
  • Domain and Selector are the email domain and selector to be used for signature verification.
  • Options is a collection of flags and should normally be 0. Bit 1, if set, prevents the Date header from being included in the signature, Bit 2, if set, prevents the Message-ID header from being included in the signature. As of Version 5.6.0.4, Bits 3, 4 and 5 prevent the custom headers List-Unsubscribe, List-Unsubscribe-Post, and Feedback-ID, respectively, from being included in the signature.
  • Path specifies the message queue location. If this argument is omitted, the default message queue location is used. In case message queuing is not used, Path is ignored.

Before this method is called, the property ContentTransferEncoding must be set to "Quoted-Printable".

See Section 5.5 of the user manual for more information.

Introduced in Version 5.3.

This is a premium feature.


Sub SendEncrypted(Msg As CryptoMessage)
Sends an encrypted message. Msg is an object creatable by the AspEncrypt component. See AspEncrypt Web site for more information.

Sub SendSigned(Msg As CryptoMessage)
Sends a digitally signed message. Msg is an object creatable by the AspEncrypt component. See AspEncrypt Web site for more information.

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

Sub SendToNewsgroup(Newsgroup As String)
Posts a message (article) to a news group specified by Newsgroup via the NNTP protocol. This method ignores addresses specified by AddAddress, etc. methods. Host must point to a valid NNTP server. Uses port 119 by default, 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.

Sub SendToQueue(Optional Path = "")
Equivalent to calling Mail.Queue = True followed by Mail.Send. Obsolete, supported for backwards compatibility only.

Function ValidateAddress(Address As String) As Integer

Performs the syntactic validation of the specified email Address. Call this method on a user-specified address to make sure its syntax is valid. This method does NOT determine if an email address actually exists. Returns the following values:

0 - Valid address
1 - Too short
2 - Too long (greater than 256 chars)
3 - No @ character
4 - Nothing before @
5 - Characters before @ must be a-z A-Z 0-9 ' _ . - +
6 - No dots after @
7 - Zero-length subdomain
8 - Characters in a subdomain must be a-z A-Z 0-9 -
9 - Characters in a top-level subdomain must be a-z A-Z 0-9
10 - Top-level subdomain must be at least 2 characters long
11 - Name part of address cannot start or end with a dot
12 - A subdomain cannot start or end with a dash (added in Version 5.4.0.6)

See Section 2.4 for more info.


Function ValidateAddressMX(Address As String, Optional DNS) As String

Determines whether Address exists via a DNS lookup of the MX records of the address's domain and connecting to the corresponding SMTP server. Returns an empty string if the address is believed to exist, and an error message otherwise. Uses DNS as the address of the DNS server for the MX record lookup. If this argument is omitted, obtains the local DNS addresses from the system registry.

See Section 2.4 for more info.

MailLogger Properties


Records As Object (Read-only)
Returns the collection of LogEntry objects each representing an individual log entry.

MailLogger Methods


Sub Clear()
Clears the log file. All records in the log are erased.

Sub Close()
Closes the log opened via the Open method.

Sub Open(Optional Path = "")
Opens the log, populates the Records collection. If Path is specified, opens the file specified by Path. If this argument is omitted, opens the default log file specified in the EmailAgent configuration panel.

Sub Refresh(Optional Path = "")
Re-populates the Records collection with the latest data.

LogEntry Properties


DateTime As Date (Read-only)
Returns the timestamp information for the log entry.

FileName As String (Read-only)
Returns the filename of the message file responsible for this entry.

Recipient As String (Read-only)
Returns the recipient's email address for the log entry. This information is particularly useful for bounced-message handling purposes. See Chapter 8 for more info.

Status As String (Read-only)

Returns the following strings:

"SUCCESS" - for a successful SMTP send.
"FAILURE" - for a non-fatal send. The message will be resent.
"ERROR" - for a fatal send. The message was moved to the \Failed folder and will not be resent.
"SYSTEM" - for a system error, such as failure to connect to the POP3 server, etc. Such entries are not associated with any particular message.
"RECEIVED" - for a successful POP3 message retrieval.


Text As String (Read-only)
Returns the entire log entry.