1. Core Features


Newsletter Signup

   

Chapter 2: Advanced Features 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

1.1 What is AspEmail.NET?

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.

1.2 System Requirements

  • Windows 2000, 2003, XP, 2008, Vista, 7, 2012, 8.
  • IIS with ASP.NET 2.0 +

1.3 Installation & Expiration Mechanism

AspEmail.NET consists of a single file, the .NET assembly Persits.Email.dll. This file houses 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.

The AspEmail.NET installation also includes the assemblies for EmailAgent.NET, a Windows service implementing message queuing. EmailAgent.NET is covered in detail in Chapter 4 of this manual.

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>

1.4 Simple Mail-Sending Script
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  Make sure AspEmail.NET is installed on your local machine and IIS is running for these links to work.

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.

1.5 Attachments
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 )

1.6 HTML and multipart/alternative

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.

1.7 Appending Body From File

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.

1.8 Authentication & TLS

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.

As of Version 5.4, AspEmail.NET and EmailAgent.NET support the SSL protocol, which is almost exactly the same as TLS but kicks in at the very beginning of the SMTP session instead of in the middle of it. An SSL connection usually takes place on port 465. To turn on the SSL mode, set the SSL property to true and Port to 465, as follows:

C#
objMail.SSL = true;
objMail.Port = 465;
VB.NET
objMail.SSL = True
objMail.Port = 465

The Username, Password, TLS and SSL properties are premium features.

Chapter 2: Advanced Features 

 

 
AspEmail.com Home Page Copyright © 1998 - 2014 Persits Software, Inc.
All Rights Reserved
AspEmail™ is a trademark of Persits Software, Inc.