Chapter 1. Core Features
1.1 What is AspEmail.NET?
1.2 System Requirements
1.3 Installation & Expiration Mechanism
1.4 Simple Mail-Sending Script
1.5 Attachments
1.6 HTML and multipart/alternative
1.7 Appending Body From File
1.8 Authentication & TLS
AspEmail.NET is the native .NET version of AspEmail, our popular mail-sending component.
Functionality-wise, AspEmail.NET is completely identical to AspEmail. It supports
file attachments, HTML format, embedded images, Unicode, TLS, secure mail, message queuing
and other features. For the complete feature summary, see Chapter 1 of the AspEmail user manual.
AspEmail.NET's basic functionality, including file attachment and HTML support,
is absolutely free. The Premium features
require a registration key, even for evaluation purposes. A free 30-day evaluation key can be obtained here.
- Windows 2000, 2003, XP, 2008, Vista, 7.
- IIS with ASP.NET 2.0 +
AspEmail.NET consists of a single file, the .NET assembly Persits.Email.dll. This
file hosts the AspEmail.NET component itself as well as the MailLogger object
used to access the message queuing log. To use AspEmail.NET, you need to place the Persits.Email.dll assembly
in the /Bin subdirectory of your .NET application.
EmailAgent, our Windows service implementing message queuing, is shared by both AspEmail and AspEmail.NET.
EmailAgent is not included with the AspEmail.NET installer. To install it, you need to install AspEmail (the classic ASP component.)
AspEmail.NET's basic functionality is absolutely free. To use its premium features, a registration key is required.
A free 30-day evaluation key can be obtained here.
When you purchase AspEmail.NET, you are sent a permanent registration key which does not expire.
An AspEmail.NET key is a 76-character Base64-encoded string.
The key needs to be placed in the Web.config or App.config file of your .NET application
as follows:
<configuration>
<appSettings>
<add key="AspEmail_RegKey" value="fH4palWtT8W..........YtWVPsS"/>
</appSettings>
...
</configuration>
To send a message with AspEmail.NET using an external SMTP server, the following simple steps should be taken:
- Create an instance of the MailSender object;
- Specify the SMTP address via the Host property;
- If the SMTP server requires a username/password, specify those via the Username and Password
properties;
- If the SMTP server also requires a secure connection via the Transport Layer Security protocol,
set the TLS property to True;
- Specify the sender's address via the From property.
- Specify the recipient's address via the AddAddress method. If the message is to be sent
to multiple addresses, the AddAddress method should be called multiple times (once per each address.)
You can also use AddCC and AddBcc methods to send to CC and Blind CC (BCC) addresses;
- Specify the message subject via the Subject property;
- Specify the message body via the Body property;
- If the message body is in HTML format, also set the IsHTML property to True.
- Call the Send method.
The following code sample sends a message interactively:
| C# |
|---|
<%@ Page Language="C#" Debug="true" validateRequest="false" %>
<%@ Import Namespace="System.Web" %>
<%@ Import Namespace="Persits.Email" %>
<script runat="server" LANGUAGE="C#">
void Send(Object Source, EventArgs E)
{
try
{
// MailSender object declaration
MailSender objMail = new MailSender();
// Set SMTP server address
objMail.Host = txtHost.Text;
// Set Username/Password if specified
if (txtUsername.Text.Length > 0)
{
objMail.Username = txtUsername.Text;
objMail.Password = txtPassword.Text;
}
// Enable TLS if so requested
if (chkTls.Checked)
{
objMail.TLS = true;
}
// Sender's address
objMail.From = txtFrom.Text;
// Recipient's address
objMail.AddAddress(txtTo.Text);
// Subject
objMail.Subject = txtSubject.Text;
// Body
objMail.Body = txtBody.Text;
// HTML format?
if (chkHTML.Checked)
{
objMail.IsHTML = true;
}
// Send message
objMail.Send();
txtResult.Text = "Success! Message sent to " +
txtTo.Text;
}
catch(Exception ex)
{
txtResult.Text = "An error occurred: <font color=red>"
+ ex.Message + "</font>";
}
}
</script>
|
| VB.NET |
|---|
<%@ Page Language="VB" Debug="true" validateRequest="false" %>
<%@ Import Namespace="System.Web" %>
<%@ Import Namespace="Persits.Email" %>
<script runat="server" LANGUAGE="vb">
Sub Send(Source As Object, E As EventArgs)
Try
' MailSender object declaration
Dim objMail As MailSender = New MailSender()
' Set SMTP server address
objMail.Host = txtHost.Text
' Set Username/Password if specified
If txtUsername.Text.Length > 0 Then
objMail.Username = txtUsername.Text
objMail.Password = txtPassword.Text
End If
' Enable TLS if so requested
If chkTls.Checked Then
objMail.TLS = True
End If
' Sender's address
objMail.From = txtFrom.Text
' Recipient's address
objMail.AddAddress(txtTo.Text)
' Subject
objMail.Subject = txtSubject.Text
' Body
objMail.Body = txtBody.Text
' HTML format?
If chkHTML.Checked Then
objMail.IsHTML = True
End If
' Send message
objMail.Send()
txtResult.Text="Success! Message has been sent to "+_
txtTo.Text
Catch ex As Exception
txtResult.Text="An error occurred: <font color=red>"+_
ex.Message + "</font>"
End Try
End Sub
</script>
|
Click the links below to run this code sample:
http://localhost/aspemail.net/manual_01/01_simple.cs.aspx
http://localhost/aspemail.net/manual_01/01_simple.vb.aspx
Note that the properties Username, Password and TLS are premium features. To use them, you must have a key (permanent or evaluation)
in the Web.config file.
AspEmail.NET is capable of sending messages with one or more attachments. To attach a file to the message,
the method AddAttachment should be used. This method accepts the full physical path
of the file being attached as the argument:
| C# |
|---|
objMail.AddAttachment( @"c:\path\mydocument.doc" );
|
| VB.NET |
|---|
objMail.AddAttachment( "c:\path\mydocument.doc" )
|
AspEmail.NET also allows memory attachments via an overloaded version of the AddAttachment method.
This overloaded version accepts a filename (without a path) and an array of bytes containing the binary
data to be attached. Memory attachments allow you to avoid creating a temporary
disk file when the data to be sent as an attachment is dynamically created or obtained from the database.
The following code snippet sends a dynamically created text string as an attachment by converting it
to an array of bytes and calling AddAttachment on it:
| C# |
|---|
StringBuilder objSB = new StringBuilder();
for( int i = 0; i < 20; i++ )
{
objSB.Append( DateTime.Now.ToString() + "\r\n" );
}
byte [] bytes = Encoding.UTF8.GetBytes( objSB.ToString() );
objMail.AddAttachment( "dates.txt", bytes );
|
| VB.NET |
|---|
Dim objSB = new StringBuilder()
For i As Integer = 0 To 20
objSB.Append( DateTime.Now.ToString + vbCrLf )
Next
Dim bytes() As Byte = Encoding.UTF8.GetBytes( objSB.ToString() )
objMail.AddAttachment( "dates.txt", bytes )
|
By default, AspEmail.NET sends the message body as plain text.
If the text string assigned to the Body property is in
HTML format, the IsHTML property must be set to True, otherwise
all HTML tags will be visible when the message is viewed by the recipient:
| C# |
|---|
objMail.Body = "<HTML>Some text<P>" +
"<IMG SRC=\"http://www.site.com/img.jpg\"></HTML>";
objMail.IsHTML = true;
|
| VB.NET |
|---|
objMail.Body = "<HTML>Some text<P>" & _
"<IMG SRC=""http://www.site.com/img.jpg""></HTML>"
objMail.IsHTML = True
|
AspEmail.NET also supports the multipart/alternative format in which the message body is specified
in both HTML and plain-text forms at the same time. This way, the message can be viewed
by email readers that are not HTML-enabled. The HTML version of the body is specified via the Body
property, and the plain-text version via the AltBody property, as follows:
| C# |
|---|
objMail.Body = "html version";
objMail.AltBody = "plain-text version";
|
| VB.NET |
|---|
objMail.Body = "html version"
objMail.AltBody = "plain-text version"
|
The AltBody property is a premium feature.
The content of the message body can be specified directly in the script by assigning a text string
to the Body property. Alternatively, it can be read from a file via the method
AppendBodyFromFile. The main version of this method accepts a single argument,
the full path to the text file being appended. The file may be in ASCII, Unicode (both big-endian and
little-endian) and UTF-8 formats.
The overloaded version of the AppendBodyFromFile method contains an additional Boolean parameter
which specifies whether the file content should be appended to Body (if set
to true) or AltBody (if set to false.)
| C# |
|---|
objMail.AppendBodyFromFile( @"c:\path\body.txt" );
|
| VB.NET |
|---|
objMail.AppendBodyFromFile( "c:\path\body.txt" )
|
The AppendBodyFromFile method is a premium feature.
SMTP servers are often configured to require an email client to provide a username and password
when sending a message. This is done to protect the SMTP server from unauthorized use by external
users, and to prevent spam. An attempt to send email via a secured SMTP server may result
in run-time errors such as
550 Relaying Denied
If your SMTP server requires authentication, you must specify
a valid username and password combination via the properties Username and Password.
Currently, AspEmail.NET only supports a single authentication method, AUTH LOGIN,
where the authentication information is transmitted to the SMTP server in clear text (unencrypted.)
If your SMTP server supports the Transport Layer Security (TLS) protocol,
you should always connect to it via a secure channel. This way, all traffic between your
mail-sending application and the SMTP server is encrypted -- not just the username/password,
but also the message headers, body and attachments.
Set the TLS property to true to enable a secure connection:
| C# |
|---|
objMail.Username = "johnsmith";
objMail.Password = "He!!o@World";
objMail.TLS = true;
|
| VB.NET |
|---|
objMail.Username = "johnsmith"
objMail.Password = "He!!o@World"
objMail.TLS = True
|
Note that some SMTP servers, such as Google's popular free smtp.gmail.com, require TLS.
An attempt to use such an SMTP server without setting TLS to true will result in an error such as
Must issue a STARTTLS command first
However, if your SMTP server does not support TLS, an attempt to connect to it via TLS
will fail as well. Check with your ISP or system administrator whether your SMTP server supports or requires TLS.
The Username, Password and TLS properties are premium features.
|
