AspEmail Manual Chapter 4: Embedded Images


4.1 Linked vs. 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:

<IMG SRC="">

The main advantage of linked images is that the message body remains small. The main disadvantages are that such messages cannot be viewed off-line, and they have a limited lifespan (images on the sender's server may be moved, deleted, or the server itself may go offline).

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:

<IMG SRC="cid:My-Image-Identifier">

A message with embedded images can be viewed off-line and remains intact over time, as images are permanently attached to the body. A message may contain regular attachments and embedded images at the same time.

4.2 The AddEmbeddedImage Method

AspEmail 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 (included with the component) as the background image for a message (note that here we use the BACKGROUND attribute of the <BODY> tag instead of <IMG>):

Mail.Body="<HTML><BODY BACKGROUND=""cid:My-Image"">...</HTML>"
Mail.AddEmbeddedImage "c:\aspemaildir\margin.gif", "My-Image"

In a similar manner, you can embed a sound file in your message using the <BGSOUND> tag, for example:

Mail.Body = "<HTML><BGSOUND=""cid:My-Sound""></BGSOUND>...</HTML>"
Mail.AddEmbeddedImage "c:\winnt\media\ringin.wav", "My-Sound"

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

To make your script more readable, you may choose to place your message body in a separate file and import it into the Body property using the method AppendBodyFromFile which accepts a full path to the text or HTML file containing the message body. A body file may look as follows:

COLOR: #427d64; FONT-FAMILY: "Arial"; FONT-SIZE: 12pt; MARGIN-LEFT: 8em
<BODY BACKGROUND="cid:My-Background-Image">
<H2>Thank-you for Shopping At Our Online Store!</H2>
<B>We hope you will come back soon.</B>
<A HREF=""><IMG SRC="cid:Persits-Software-Logo" BORDER=0></A>

The following code sample demonstrates the usage of AddEmbeddedImage and AppendBodyFromFile:

<% ' change to address of your own SMTP server
strHost = ""

If Request("Send") <> "" Then
Set Mail = Server.CreateObject("Persits.MailSender")
' enter valid SMTP host
Mail.Host = strHost
Mail.From = ""
Mail.FromName = "Persits Software Sales"
Mail.AddAddress Request("To")

' message subject
Mail.Subject = "Thank-you for your business"
' append body from file
strBodyPath = Server.MapPath(".") & "\SampleBody.htm"
Mail.AppendBodyFromFile strBodyPath

' Add embedded image for background
strImagePath = Server.MapPath(".") & "\margin.gif"
Mail.AddEmbeddedImage strImagePath, "My-Background-Image"

' Add embedded image for logo
strImagePath = Server.MapPath(".") & "\ps_logo.gif"
Mail.AddEmbeddedImage strImagePath, "Persits-Software-Logo"

Mail.Send ' send message
Response.Write "Success!"
End If
<FORM ACTION="EmbeddedImages.asp">
Enter email: <INPUT TYPE="TEXT" NAME="To">

Click the links below to run this code sample:

4.3 The AddEmbeddedImageMem Method

The previous chapter described the method AddAttachment and its "memory" counterpart AddAttachmentMem which attaches a file from memory rather than disk. Like AddAttachment, the AddEmbeddedImage method also has a memory counterpart, AddEmbeddedImageMem, which expects three arguments: the file name, Content ID, and memory array containing the binary content of the file. The latter is usually a recordset value containing a file blob, or a memory upload.