AspEmail.NET Manual Chapter 1: Core Features
Contents
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 • 2016 • 2019.
- IIS with ASP.NET 2.0 +
- .NET Core 2.0+ on Windows and Linux
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:
<appSettings>
<add key="AspEmail_RegKey" value="fH4palWtT8W..........YtWVPsS"/>
</appSettings>
...
</configuration>
AspEmail.NET is compatible with .NET Core 2.0 on Windows, Linux and other platforms. To use AspEmail.NET on .NET Core, the following steps must be taken:
- Put the AspEmail.NET assembly Persits.Email.dll in the /Bin subfolder of your application.
-
The key is to be specified via the .RegKey property of the MailSender object as there are no .config files on .NET Core:
objMail.RegKey = "fH4p0HVc1q....KQ7lw0mlavXxTG1a"; -
The Project file must contain the following entries:
<ItemGroup>
<Reference Include="AspEmail.NET">
<HintPath>bin\Persits.Email.dll</HintPath>
</Reference>
<PackageReference Include="System.Configuration.ConfigurationManager" Version="4.6"/>
<PackageReference Include="System.Security.Cryptography.Pkcs" Version="4.6"/>
...
</ItemGroup>
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:
<%@ 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><
<%@ 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:
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:
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:
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 );
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:
"<IMG SRC=\"http://www.site.com/img.jpg\"></HTML>";
objMail.IsHTML = true;
"<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:
objMail.AltBody = "plain-text version";
objMail.AltBody = "plain-text version"
The AltBody property is a premium feature.
1.1 What is AspUpload?
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 argument which specifies whether the file content should be appended to Body (if set to true) or AltBody (if set to false.)
As of Version 5.6, the 2nd argument can also be set to a string specifying the content-type of the alternative body being appended. For more information, see Section 1.9 below.
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:
objMail.Password = "He!!o@World";
objMail.TLS = true;
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:
objMail.Port = 465;
objMail.Port = 465
The Username, Password, TLS and SSL properties are premium features.
Prior to Version 5.5, AspEmail.NET only supported TLS 1.0, a protocol currently in the process of being decommissioned due to its various vulnerabilities. As of Version 5.5, AspEmail.NET supports both TLS 1.0 and TLS 1.2. The latter is a more secure protocol based on strong cipher and hash algorithms. AspEmail.NET 5.5+ uses TLS 1.2 by default. To force it to use TLS 1.0 instead, set the new property TLSVersion to the string "1.0", as follows:
A cipher suite is a combination of various cryptographic algorithms working together to carry out a TLS session. These algorithms include a public-key cipher for key exchange (such as RSA or Diffe-Hellman), a symmetric cipher for data encryption (such as 3DES or AES), one or more one-way hash functions for key generation and message authentication, such as SHA1/MD5 or SHA256, and in some cases a digital signature algorithm.
AspEmail.NET currently supports the following cipher suites:
The cipher suites 009C and C02F based on the Galois/Counter Mode (GCM) are available as of Version 5.6.0.5301. Also, as of this version, the cipher suite chosen by the SMTP server during the last successful TLS session can be retrieved via the TLSVersion property. The value returned by this property is in the format "1.2; Cipher Suite C02F" where the prefix such as 1.2 is the TLS version and the hexadecimal number such as C02F is the cipher suite code (see the table above.)
1.9 Extended Multipart/Alternative Support
1.9.1 Body and AltBody
Multipurpose Internet Mail Extensions (MIME), the format in which most email messages are transmitted, allows a message body to be specified in several alternative versions at the same time. This feature, referred to as multipart/alternative, was originally designed to allow a message body to be specified in both HTML and plain-text forms to accommodate text-only email viewers.
Each sub-section within a multipart/alternative section of the message is preceded with a Content-Type header specifying this sub-section's format, such as Content-Type: "text/plain" for the plain-text version of the message body, and Content-Type: "text/html" for the HTML version.
Since its early days, AspEmail has supported the dual plain-text/HTML message bodies via the properties Mail.Body and Mail.AltBody. The HTML version of the body is to be specified via the former, and plain-text version via the latter, as follows:
Mail.AltBody = "Hello World!"; ' // Plain-text version
Mail.AltBody = "Hello World!" ' Plain-text version
If the content of the message body were to be loaded from a disk file, the method AppendBodyFromFile can be used. This method's 2nd optional argument specifies whether it is Mail.Body that the content of the file is to be appended to (if set to True or omitted) or Mail.AltBody (if set to False). For example:
Mail.AppendBodyFromFile(@"c:\path\body.txt", false);//Append AltBody
Mail.AppendBodyFromFile("c:\path\body.txt", False) ' Append AltBody
1.9.2 AddAltBody Method
As of Version 5.6, AspEmail's support for multipart/alternative is no longer limited to just two content types (text/plain and text/html). Via the new method AddAltBody, any number of multipart/alternative subsections with arbitrary content types can be added to the email message. With the help of this method, messages generated by AspEmail can host various advanced content, such as accelerated mobile pages (AMP), calendars, etc. The method expects two string arguments: the content for the multipart/alternative section, and its content-type.
The following snippet generates a basic AMP message for which the content-type is "text/x-amp-html":
str += "<html amp4email>";
str += "<head>";
str += "<meta charset=\"utf-8\">";
str += "<script async src=\"https://cdn.ampproject.org/v0.js\"></script>";
str += "<style amp4email-boilerplate>body{visibility:hidden}</style>";
str += "</head>";
str += "<body>";
str += "Hello, AMP4EMAIL world.";
str += "</body>";
str += "</html>";
objMail.AddAltBody(str, "text/x-amp-html");
...
str = str & "<html amp4email>"
str = str & "<head>"
str = str & "<meta charset=""utf-8"">"
str = str & "<script async src=""https://cdn.ampproject.org/v0.js""></script>"
str = str & "<style amp4email-boilerplate>body{visibility:hidden}</style>"
str = str & "</head>"
str = str & "<body>"
str = str & "Hello, AMP4EMAIL world."
str = str & "</body>"
str = str & "</html>"
objMail.AddAltBody(str, "text/x-amp-html")
...
The AddAltBody method can be used to specify the HTML and plain-text versions of the message body in lieu of Body and AltBody properties. The content-type value must be set to "text/html" and "text/plain", respectively:
objMail.AddAltBody( htmlText, "text/html" );
// Same as objMail.AltBody = plainText
objMail.AddAltBody( plainText, "text/plain" );
objMail.AddAltBody( htmlText, "text/html" )
' Same as objMail.AltBody = plainText
objMail.AddAltBody( plainText, "text/plain" )
The text specified via AddAltBody can be retrieved via the method GetAltBody which expects the content-type as an argument, as follows:
A call to the method ResetAll clears the list of alternative bodies along with all other lists and properties.
1.9.3 Sending Calendar Invitations
As of Version 5.6, the above described method AppendBodyFromFile has been retrofitted to be used with any alternative body and not just plain-text and HTML ones. In addition to True and False, the 2nd optional argument can now be set to a content-type string. The following code snippet creates a calendar invitation by appending a .ics file to the "text/calendar" alternative body:
