AspEmail.NET Manual Chapter 2: Advanced Features

2.1.1 Quoted-Printable Format

AspEmail.NET is capable of sending messages in alphabets other than US-ASCII by supporting the "Quoted-Printable" format. This format is described in RFC-2045. The idea of the format is that characters with codes less than 33 and greater than 126 are represented by an "=" followed by a two digit hexadecimal representation of the character's value. For example, the decimal value 12 (US-ASCII form feed) is represented as =0C, and the decimal value 61 (US-ASCII "=") can be represented as =3D.

AspEmail.NET encodes the message body in the Quoted-Printable format automatically if the ContentTransferEncoding property is set to the string "Quoted-Printable".

The ContentTransferEncoding property is a premium feature.

2.1.2 UTF-8 Encoding

UTF-8 (Unicode Transformation Format, 8-bit encoding form) is the recommended format to be used to send Unicode text over the Web and email. UTF-8 represents a Unicode value as a sequence of 1, 2, or 3 bytes. UTF-8 is compatible with ASCII format.

AspEmail.NET offers full UTF-8 support in both a message body and headers. To send a UTF-8 encoded message, you must set the CharSet property to the string "UTF-8" (case is immaterial), and ContentTransferEncoding to "Quoted-Printable". The following code snippet sends a message with the body in Russian:

The CharSet property is a premium feature.

2.1.3 Header Encoding

If you wish to send a message with certain mail headers such as Subject:, To: or From: containing non-US-ASCII characters, you should use the method EncodeHeader to encode your character string. The main version of the EncodeHeader method takes a single parameter, the header string. The overloaded version of the method also takes a 2nd parameter, the character set, which is "ISO-8859-1" by default.

The following code snippet specifies a message Subject in Russian, UTF-8 encoded:

The EncodeHeader method should also be used if you need to include Emojis in your message subject. Emojis are characters outside the standard 0000-FFFF Unicode range. They need to be encoded with two 16-bit numbers as shown in the right column of the table below:

These two numbers are referred to as high surrogate code point and low surrogate code point. The formulas to convert the Emoji's code point to its high and low surrogates are as follows:

hi = (cp - 0x10000) / 0x400 + 0xD800
lo = (cp - 0x10000) % 0x400 + 0xDC00

The following code snippet includes the two Emojis above in a message subject:

2.1.4 Other Character Set Values

The string "UTF-8" is not the only valid value for the CharSet property and the second parameter to the EncodeHeader method. Other values include "Windows-1250", "Windows-1251", "shift_jis", "chinese", and others. Below is the complete list of valid CharSet values:

2.1.5 Code Sample

The following code sample is very similar to the one provided in Chapter 1 of this manual except it uses the CharSet and ContentTransferEncoding properties and EncodeHeader method. The rest of the script is not shown here for brevity.

Click the links below to run this code sample:

http://localhost/aspemail.net/manual_02/02_unicode.cs.aspx http://localhost/aspemail.net/manual_02/02_unicode.vb.aspx

2.2.1 Why Use Embedded Images?

Commercial e-mail messages often contain images, graphics and other design elements. When a message is sent in the HTML format, images used in the message body can be either linked or embedded. Linked images are not part of the message itself. They are usually hosted by the message sender and referenced in the message body via an <IMG> tag pointing to the sender's server, as follows:

The main advantage of linked images is that the message body remains small. The main disadvantage is that most email clients these days block linked images for security purposes and the message appears broken to the viewer.

Unlike linked images, embedded images are part of the message itself. They are similar to regular attachments, although they use the multipart/related format, as opposed to multipart/mixed. An embedded image is also referenced in a message body using an <IMG> tag, but instead of a URL, an image identifier, or Content ID, is used, as follows:

Messages with embedded images are usually not tempered with by the email client, can be viewed off-line and remain intact over time, as the images are permanently attached to the body. A message may contain regular attachments and embedded images at the same time.

2.2.2 AspEmail.NET's Support for Embedded Images

AspEmail.NET offers support for embedded images via the method AddEmbeddedImage which takes two arguments: the physical path to an image file, and its Content ID, which is simply an arbitrary string without spaces. If your message contains multiple embedded images, each must be assigned a unique Content ID. The following example uses the file margin.gif as the background image for a message (note that here we use the BACKGROUND attribute of the <BODY> tag instead of <IMG>):

Note: Content-IDs are case-sensitive. Make sure the values specified by "cid:..." and AddEmbeddedImage fully match.

Like AddAttachment, the AddEmbeddedImage method has an overloaded "memory" version which allows you to embed an image coming from memory (such as a database blob) as opposed to disk. This method expects three arguments: the filename (without a path), Content ID and memory array of bytes containing the image:

2.2.3 Code Sample

The following code sample sends a message containing two embedded images, one used for the body margin and the other embedded in the message body. The body text is read from a text file via the method AppendBodyFromFile described in the previous chapter.

The body text file MessageBody.htm looks as follows:

The code snippet responsible for image embedding is as follows:

Click the links below to run this code sample:

http://localhost/aspemail.net/manual_02/02_embeddedimages.cs.aspx http://localhost/aspemail.net/manual_02/02_embeddedimages.vb.aspx

AspEmail.NET is capable of validating the syntax of an email address. As of Version 5.2, it is also able to determine, with a high degree of certainty, whether a particular email address actually exists.

The method ValidateAddress takes an email address as an argument and returns 0 if the address is syntactically valid. A number greater than 0 means a syntax error. All possible return values are as follows:

For example:

The ValidateAddress method makes no determination whether the email address being validated actually exists. As of Version 5.2, AspEmail.NET offers another method, ValidateAddressMX, which internally calls ValidateAddress to determine its syntactic correctness, performs a DNS lookup of the MX records for the address's domain, and then contacts the corresponding SMTP server to determine if it recognizes the address as valid.

ValidateAddressMX expects two arguments: the email address being validated and, optionally, the IP address of the DNS server for the MX record lookup. If the 2nd argument is omitted, the method obtains the addresses of the local DNS servers from the system registry. ValidateAddressMX returns an empty string if the email address is successfully validated, or an error message if the validation fails.

To validate an address against its corresponding SMTP server, ValidateAddressMX sends three SMTP commands: HELO, MAIL FROM and RCPT TO. The value used for the HELO command is the Helo property, for the MAIL FROM command the MailFrom property, and for the RCPT TO command the address being validated. If MailFrom is not specified, the address being validated is used for the MAIL FROM command as well. It is recommended that you specify your domain name for the Helo property, and your valid email address for the MailFrom property before calling ValidateAddressMX, as follows:

Note that the validation procedure performed by the ValidateAddressMX method is not 100% accurate. An error returned by the method does not always mean the address is invalid, and a lack of error is not always an indication the address exists.