AspEmail.NET Object Reference

Persits.Email.MailSender Member List

Persits.Email.MailLogger Member List

Persits.Email.LogEntry Member List

Persits.Email.MailSender Properties


string AltBody (Read/Write)

Specifies an alternative text version of a message while Body specifies an HTML version. When this property is set, AspEmail.NET 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.


string Body (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.

string CharSet (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.NET to perform a conversion of message body characters into the specified character set. If this property it set to "UTF-8", AspEmail.NET uses the UTF-8 encoding. To learn more, and for a list of valid values for this property, see Section 2.1.4.

This is a premium feature.


string ConfigPath (Read/Write)
Returns the location of the current configuration file. This property was introduced in version 5.3.0.3127 and is useful when the component is used in classic ASP.

string ContentTransferEncoding (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.NET 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.


DateTime Expires (Read-only)
Returns the expiration date of the component's premium features. Returns 9/9/9999 if a valid registration key is installed. Returns DateTime.MinValue if the expiration value in the .config file is corrupt or missing.

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

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

string Helo (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.NET uses a value returned by the property Environment.MachineName.

string Host (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.

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

bool MailFrom (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.

string Password (Read/Write)

See comments to the property Username.

This is a premium feature.


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

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

bool Queue (Read/Write)

Enables message queuing. False by default. If set to True, specifies that a subsequent call to Send place the message in a message queue specified by QueuePath to be processed by EmailAgent or EmailAgent.NET. See Chapter 4 for more info.

This is a premium feature.


string QueueFileName (Read-only)
Returns the name of a message file generated by a call to Queue = True followed by Send. See Chapter 4 for more info.

string QueuePath (Read-only)
Specifies the message queue path to place the message file in by a call to Queue = True followed by Send. See Chapter 4 for more info.

string RegKey (Write-only)
Specifies the registration key. If this property is not set, AspEmail.NET will look for a registration key in the application's .config file. For more information, see Section 1.3 - Installation & Expiration Mechanism.

bool SSL (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 introduced in Version 5.4.

This is a premium feature.


string Subject (Read/Write)
Specifies the message subject.

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

DateTime Timestamp (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.

bool TLS (Read/Write)

Enables the Transport Layer Security (TLS) protocol. Should be set to True when the SMTP server pointed to by Host requires TLS.

This is a premium feature.


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

string Username (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.NET supports the AUTH=LOGIN authentication method.

This is a premium feature.


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

Persits.Email.MailSender Methods


void AddAddress(string Address)
void AddAddress(string Address, string 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.

void AddAltBody(string Body, string ContentType)

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 1.9 - Extended Multipart/Alternative Support for more information.

This is a premium feature.


void AddAttachment(string Path)
void AddAttachment(string Name, byte[] Blob)
Adds a file to the list of file attachments to be sent with the message. A full physical Path must be specified. If the file is attached from memory, its Name (without a path) and binary Blob must be specified. This method can be called multiple times per message.

void AddBcc(string Address)
void AddBcc(string Address, string Name)
Adds an email address to the message's BCC: (blind carbon copy) list. This method can be called multiple times per message.

void AddCC(string Address)
void AddCC(string Address, string 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.

void AddCustomHeader(string Header)

Adds a custom Header to the message, e.g.

objMail.AddCustomHeader( "Return-Receipt-To: <name@domain.com>" );

You can use this method to specify a custom Message ID for your message, e.g.

objMail.AddCustomHeader( "Message-ID: abc12356" );


void AddEmbeddedImage(string Path, string ContentID)
void AddEmbeddedImage(string Name, string ContentID, byte[] Blob)

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">. Path is a full physical path of the image on disk. Name is a filename (without a path) if the image is opened from memory. Blob is a binary array containing the image.

See Section 2.2 -- Embedded Images for more info.

This is a premium feature


void AddReplyTo(string Address)
void AddReplyTo(string Address, string 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.

void AppendBodyFromFile(string Path)
void AppendBodyFromFile(string Path, bool AddToBody)
void AppendBodyFromFile(string Path, string ContentType)

Appends the Body property from a text or HTML file specified by Path. If AddToBody is set to False, the content of the file is appended to AltBody instead of Body. )

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 ContentType to the appropriate content-type value, such as "text/html", "text/plain", "text/calendar", etc.

This is a premium feature.


string EncodeHeader(string Header)
string EncodeHeader(string Header, string Charset)

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.

objMail.Subject = Mail.EncodeHeader("La fête à Jean-Sébastien Bach");

or

objMail.AddAddress( "oystein@somecompany.no", objMail.EncodeHeader("Øystein") );

Charset can be set to "UTF-8" or any valid character set code described in Section 2.1.4. "ISO-8859-1" by default.


MailSender GetAccessToken(string Service, string Code, bool Refresh)

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

For more information, see Section 3.5 - Google GMAIL oAuth.


string GetAltBody(string ContentType)

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 1.9 - Extended Multipart/Alternative Support for more information.


void LogonUser(string Domain, string Username, string Password)

Impersonates the specified user account. If Domain is empty, the local computer is used to validate the Username/Password. This method is useful when AspEmail.NET is used in a classic ASP environment to send digitally signed mail via a certificate loaded from a .PFX file.

This method was introduced in Version 5.3.0.3218.


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

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

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

void RevertToSelf()

Ends impersonation begun by the LogonUser method.

This method was introduced in Version 5.3.0.3218.


void Send()
void Send(string Path)
Sends a message. Throws exceptions in case of an error. If 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 or EmailAgent.NET. The name of the message file thus created can be retrieved via the property QueueFileName. Path specifies the message queue location. If Path is not specified, the value specified via the QueuePath property is used. If QueuePath is also empty, the default message queue path is obtained from EmailAgent's configuration section of the system registry. In case message queuing is not used, Path is ignored.

void SendCertified(X509Certificate2 Cert, string Domain, string Selector, int Options)
void SendCertified(string Path, string Password, string Domain, string Selector, int Options)

Sends a message equipped with a DKIM signature.

  • Cert is the signer certificate. As of Version 5.3.0.3218, the certificate can be specified via the Path to the certificate file in PFX format and its Password.
  • 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.5319, Bits 3, 4 and 5 prevent the custom headers List-Unsubscribe, List-Unsubscribe-Post, and Feedback-ID, respectively, from being included in the signature.

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

See Section 3.4 of the user manual for more information.

This is a premium feature.


void SendEncrypted(X509Certificate2 Cert)
void SendEncrypted(X509Certificate2Collection Certs)
void SendEncrypted(string Path)

Sends an encrypted message. Uses Cert's public key to encrypt the message, or the public keys of all certificates in the Certs collection. As of Version 5.3.0.3218, the certificate can be specified via the Path to the certificate file. See Chapter 3 for more information.

This is a premium feature.


void SendSigned(X509Certificate2 Cert)
void SendSigned(string Path, string Password)

Sends a digitally signed message. Uses Cert's private key to sign the message. As of Version 5.3.0.3218, the certificate can be specified via the Path to the certificate file in PFX format and its Password. See Chapter 3 for more information.

This is a premium feature.


void SendSignedAndEncrypted(X509Certificate2 SignerCert, X509Certificate2 RCert)
void SendSignedAndEncrypted(X509Certificate2 SignerCert, X509Certificate2Collection RCerts)
void SendSignedAndEncrypted(string Path, string Password, string Path2)

Sends a message which is first digitally signed with SignerCert's private key and then encrypted with RCert's public key or the public keys of all certificates in the RCerts collection. As of Version 5.3.0.3218, the signer certificate can be specified via the Path to the certificate file in PFX format and its Password, and encryption certificate file via Path2. See Chapter 3 for more information.

This is a premium feature.


void SendToNewsgroup(string Newsgroup)

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.


int ValidateAddress(string Address)

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

See Section 2.3 for more info.


string ValidateAddressMX(string Address)
string ValidateAddressMX(string Address, string DNS)

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.3 for more info.

Persits.Email.MailLogger Properties


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

Persits.Email.MailLogger Methods


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

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

void Open()
void Open(string 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.

string OpenMostRecent(string Folder)
Opens the most recent log file in the folder specified by Folder. Returns the filename (without a path) of the log file being opened.

void Refresh()
Re-populates the Records collection with the latest data.

Persits.Email.LogEntry Properties


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

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

string Status (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.


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

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