HTML Mail

CustomMailer supports the sending of HTML mail in addition to regular plain text mail.  Sending HTML mail requires some extra work, but the results are well worth it.

Using HTML mail and Alternate Text
Many email clients, in particular Netscape Messenger, Microsoft Outlook, and Eudora, now support the ability to read mail received in HTML format.  HTML mail messages can contain multiple fonts, colors, backgrounds, images, links, tables, CGI scripts, even applets!  Basically, an HTML mail message can contain anything that might appear in a regular HTML web page.  Moreover, CustomMailer can fully customize these HTML mail messages, so you can use CustomMailer tags and macros to create any part of your HTML email message, whether your content or the HTML tags themselves.

Some email clients (for example, older versions of Lotus Notes, traditional Unix email clients, and other proprietary email programs) will not display mail in HTML format.  For this reason CustomMailer also supports the provision within the Internet mail standard for an "Alternate Text" message (technically, this is the MIME type: multipart/alternative).  The alternate text message is written in plain text and accompanies the HTML message.  If a particular recipient's mail reader doesn't support HTML, they should instead see the Alternate Text message in their mailer and may (or may not) receive the HTML message as a file attachment.  CustomMailer allows the HTML and Alternate Text message to be completely independent of each other and both can be fully customized using CustomMailer tags and macros.

NOTE: Some mail readers that don't support HTML will display a text-only view extracted from the HTML message rather than the Alternate Text message.  Thus, you are advised to compose the HTML and Alternate Text parts of your message so that either is intelligible no matter how your recipients' mail readers handle HTML mail.
 

Composing your HTML mail message
The easiest way to create your HTML mail message is to use your favorite browser or other HTML creation tool.  Simply compose your message in HTML and insert tags like |FirstName| or |Date| as you wish inside your HTML mail message.  If you are ambitious, you can even have CustomMailer tags and macros generate parts of the HTML tag syntax itself.  Save your HTML mail in a file ending with .htm or .html.  When CustomMailer customizes the HTML mail message for a given recipient, all the tags and macros are expanded in the usual manner, and the final result is the actual HTML that gets sent to that recipient.

NOTE: Beginning with CustomMailer 2.0, the default tag indicator character was changed from "%" to "|".  This is primarily because a number of places in HTML syntax make use of the "%" character, for example, when indicating that a given image or table should span "50%" of the page width, so that using some other tag indicator character became advisable.  The vertical bar character "|" seems to be a safe choice for both HTML and non-HTML messages and is recommended.

Inside CustomMailer, use the "Open Message Template" menu command to open your .htm or .html file.  This will signal CustomMailer that you want to use HTML mail.  CustomMailer will split the message body area horizontally into two areas.  The left area will show your HTML Source and the right area shows your Alternate Text message.  A split panel divides the HTML Source and Alternate Text and can be dragged to resize the two areas.

A new button also appears to the left of the HTML Source, labeled ">>HTML Page".  When you hit this button, CustomMailer will start up your default browser and show you the HTML source as a real HTML page inside your browser.  You can view in your browser either the Template (shown in blue = tagged message for all recipients) or the expanded Message (shown in black = expanded message for a selected recipient), depending upon whether you were in "View as Template" or "View as Message" mode when you clicked on ">>HTML Page". 

Even better, you can "Edit" either the Template or the Message in your browser.  If you simply "Save" the result in your browser back into the file name that the browser opened up with (which CustomMailer sets to tempCustomMailerHTMLDocument.html), then when you return to CustomMailer your changes will be automatically read back as your updated Template if you were in View as Template mode, or as your updated Message if you were (and still are) in View as Message mode.  This level of integration between your browser and CustomMailer lets you easily go back and forth to compose and test both your HTML mail template and customized messages.  You do not need to exit your browser when going back to CustomMailer, just be sure to "Save" any edits you make in the browser and CustomMailer will pick them up when the main CustomMailer windows is brought to the front (CustomMailer does this by looking for whether the "Last Modified" date on the "temp" file has changed).  Likewise, if you make further changes to the HTML in CustomMailer and wish to view them back in the browser, just hit ">>HTML Page" again.

You can also compose your HTML mail message directly in CustomMailer if you don't mind working directly in HTML source code.  Use the "New Message Template" command and specify that you want an "HTML" message.  You can then type (or cut-and-paste) HTML source directly into the HTML Source area.  Even if you do most of your editing in the browser, you will probably find it useful to make small, quick changes directly in the CustomMailer HTML source window.

To complete your HTML mail message, you fill out the message header fields (TO, FROM, etc.) in the standard way. 

Alternate Text
You enter your alternate text (plain text) message in the Alternate Text area.  This area works exactly like a regular CustomMailer plain text (.txt) mail message and you can enter anything you want including tags and macros.  When you create a new HTML mail message, a minimal Alternate Text message is provided by default that says:

This email message was sent in HTML format.
If your email reader is not able to display
HTML email and has substituted this message,
please contact the sender to obtain a copy
you can read.

Some CustomMailer users just use this message for the Alternate Text.  Others change it to contain a URL link to a generic copy of the HTML message residing on their web site, for example:

If you can't read this message, please go to http://www.yourdomain.com/copyOfMessage.html

Other CustomMailer users like to have a full plain text equivalent of their HTML message for the Alternate Text.  In this case the easiest thing to do is to complete your HTML message, then view your HTML message in your favorite web browser, then while viewing the HTML page in the browser (not the HTML source), select and copy the desired text and paste it into the Alternate Text area.  You may need to edit the line breaks and other spacing that results.  NOTE: In Netscape, if you are in Edit Mode when you select and copy your text, then no superfluous line breaks will be introduced.

Also, you can also have a completely blank Alternate Text message, in which case CustomMailer sends a pure text/html MIME message with no multipart/alternative portion.

Finally, CustomMailer users may prefer to compose an independent plain text message not equivalent to the HTML message.  You can either compose the message directly in the right hand text area or compose the message in a separate word processing application, then copy and paste the contents into the right hand text area.  There currently is no way to read the Alternate Text portion of the message from a separate file.  

When you use the CustomMailer "Save" menu command to save the message, the HTML source, Alternate Text, and all the header fields are saved into a single .html file.  The Alternate Text and header fields are stored using a syntax similar to the non-HTML CustomMailer messages, i.e., with keywords like TO:, FROM:, SUBJECT:, etc. followed by their respective values.  The Alternate Text is saved as one or more lines, with each line prefaced by the keyword ALTERNATE TEXT:. The Alternate Text lines and mail header lines are all saved inside standard HTML comment fields delimited by <!-- and --> marks, each on their own line beginning in column 1.  As a result, you can open the resulting file in your standard browser, and the extra CustomMailer information will not affect the HTML page view.  The alternate text and header comment lines can appear in any order and appear anywhere inside the .html file, though CustomMailer will always write them out first.  Any changes or additions you make to the special CustomMailer header and Alternate Text lines (using the browser's "Edit HTML source" capability or in a regular text processor) will be picked up when the message is read back into CustomMailer.

URLs vs. self-contained HTML mail
The most common way commercial emailers include images, sounds, etc. in HTML mail is to specify them as URLs which are accessible on-line, for example:
    <IMG SRC=http://www.yoursite.com/image.gif>
where image.gif is available on-line at the indicated web site.  The primary advantage of this is keeping the HTML mail small and transmission time quick, since CustomMailer does not need to send (and resend) copies of the images, sounds, etc. with each individual email.  Another advantage is that the link can point to content on your web site that is can be continuously updated so as to be current whenever the email is read.  

To accomplish this in browsers such as Netscape Communicator, when you edit your HTML page and specify your image, you need to enter the complete URL (e.g. http://www.yoursite.com/image.gif) and check the box that says "Leave image at the original location" so that it doesn't save the image locally and change the reference to the local (non-URL) copy (e.g. image.gif).

However, a big disadvantage of this technique is that it requires the recipient to be on-line when they read their email.  Frequently this is true since they are on-line to pull their mail from their mail server, plus most people in companies and increasing numbers of people at home have "always-on" Internet connections such as T1 or DSL.  But a lot of people, especially those with laptops or with dial-up connections, pull their mail then read it off-line.  Since they are not on-line when they view the HTML mail, for them the image links are broken.  One thing that helps a bit is to include the ALT image tag, e.g.:
    <IMG SRC=http://www.yoursite.com/image.gif ALT="Company logo">
so that if the image is not available, the recipient at least sees some indication of what they are missing.

But there is an alternative solution to this problem.  CustomMailer also supports the "Content-ID" (cid:) mechanism for including a copy of images and sounds "in-line" with each individual HTML email message.  To cause this to happen, you simply compose your HTML email and specify your references not as URLs (http://www...) but as local file references.  These can either be "relative" file references such as:
    <IMG SRC=image.gif>
    <IMG SRC=subfolder/image.gif>
    <IMG SRC=../image.gif>
where the SRC field specifies the file image.gif relative to the folder the .html file is in on your computer.  Or, you can specify "absolute" file references such as:
    <IMG SRC=file:///C:/folder/image.gif>
or
    <IMG SRC=C:/folder/image.gif>
specifying the direct path to the file image.gif on your computer.  Most HTML creation tools such as Netscape give you the option of specifying "URL is relative to page location" to select between these relative and absolute notations.  

In either case, CustomMailer will take any local file reference as an indication that you want this sent in "Content-ID" style, including a copy of image.gif along with each HTML mail message.  CustomMailer will MIME-encode the image.gif file, include it in-line with your HTML mail, and replace the reference in your HTML mail with the appropriate cid: notation.  When the message gets to your recipient, everything will be put back together and image.gif will appear in your message.  The big advantage of this is that your HTML mail messages are self-contained and can be read whether or not the recipient is on-line.  The disadvantage is that your emails will be correspondingly bigger and therefore your mailing will take that much longer.  For these reasons, it is a good idea to be judicious in your use of in-line images and try to keep them small and few in number.

CustomMailer has no problem with your including both URLs and local file references in the same HTML mail.

HTML vs. plain text recipients

CustomMailer has a feature called "Don't send HTML if", which is one of the "Sending Exclusions" controlled from the Preferences dialog under the Message sending tab.  This features allows you to use a tag or macro to control whether to send HTML mail or plain text mail to a given recipient.  A popup menu in the Preferences dialog by default has the value "Always send HTML", in which case all selected mailing list rows will be sent HTML email (including the Alternate Text portion).  Or you can use the popup to choose any tag (= mailing list column name) or macro plus specify a value for it to EQUAL.  In this case, when CustomMailer attempts to send each selected row in your mailing list, it first evaluates the tag or macro for that recipient and determines if the resulting value is EQUAL to the value you specify (this test is case-sensitive).  If so, only the Alternate Text portion of your email is sent as a plain text message for that row, otherwise the HTML message is sent (including the Alternate Text portion).

This feature is useful for distinguishing which of your recipients prefer to receive plain text email instead of HTML mail.  For example, you might add a column called HTML and insert a "N" for those recipients who should only receive plain text email.

Useful tips
The CustomMailer distribution includes an example of an HTML mail message with images, multiple fonts, bullets, URL and email links, plus an Alternate Text message, in the file SampleHTMLMessageTemplate.html.

Almost all email readers that don't support HTML mail will at least turn URLs in your message into clickable links.  For this reason, you may wish to reword your Alternate Text messages to take advantage of this feature, for example
    In HTML mail:  Please visit the Wildcrest Associates web site
    In Alternate Text: Please visit our web site at http://www.wildcrest.com
Since some mail readers that don't display HTML show a text-only version of your HTML message rather than the Alternate Text message, you might want to always include explicit URLs in both your HTML and Alternate Text messages.

As mentioned above, another approach to dealing with recipients who can't read HTML mail is to place a generic copy of your email message on your web site and have your Alternate Text message start with a line like:
      To view this message in HTML, please go to http://www.yourcompany.com/message.html
The URL will generally be turned into a link that these recipients can click on to view your message in their regular browser.

Almost all email readers will also turn URLs like:
   mailto:products@wildcrest.com
into clickable links.  This provides another useful way to create more functional emails even for plain text messages.  This syntax supports a number of extensions such as:
   mailto:products@wildcrest.com?subject=Unsubscribe
   mailto:products@wildcrest.com?subject=Unsubscribe&body=Please%20remove%20me
or even
   mailto:products@wildcrest.com?subject=Unsubscribe&body=Please%20remove%20|email|

Notice the use of the notation %20 for spaces, since spaces are not allowed in URLs.  In a similar way you can produce clickable links for images or sounds in plain text messages.  See the Message Template section of "Frequently Asked Questions" for more details.

NOTE: Older versions of Lotus Notes seems to have particular problems with HTML mail.  Some versions will drop the images but display the rich text content.  Others appear to truncate the message at the first embedded content (image, table, etc.).  In either case, because it thinks it has displayed the HTML Mail, it discards the Alternate Text, so in the worst case the recipient sees little or nothing.  However, in our experience all versions of Lotus Notes will at least show whatever text appears in the HTML message before the first embedded component and even convert URLs in that text to clickable links.  Therefore, a conservative strategy for dealing with this case is to always start your HTML message (not just your Alternate Text) with a line like:
      To view this message in HTML, please go to http://www.yourcompany.com/message.html
This line will get through and give the recipient a viable option, even if everything else gets omitted.  Fortunately, newer versions of Lotus Notes handle HTML mail correctly, including Content-IDs.

NOTE: The Netscape mail reader provides an option whereby the recipient can check or uncheck View Attachments Inline.  If checked (which is the installation default), an HTML message will show up like an HTML page in the body of the message, as you would expect.  However, if unchecked, Netscape will show a link which when clicked will open a separate window with the Alternate Text message, and no way is provided to read the HTML message.  This appears to be either a bug or a flawed design, and indeed Netscape does the same thing even for HTML messages sent by Netscape.  As a workaround, if in CustomMailer you leave the Alternate Text section completely empty, CustomMailer will send the message with a single section using MIME type text/html and Netscape will show this as an HTML page in the body of the message regardless of the View Attachments Inline setting.  But obviously this prevents you from using the Alternate Text feature for users with mail readers not capable of reading HTML.  Since the View Attachments Inline feature is normally checked, and since Netscape will still show the Alternate Text message even if it is unchecked, we generally opt for using the Alternate Text feature.

Of course, if you know which recipients can receive HTML or not, then using the "Don't send HTML if" feature is the best way to ensure that everyone gets the style of email they can read.  But if you don't know this information, then for email that absolutely, positively has to be readable by all recipients, it is probably best to forego HTML mail and use plain text, although over time as email client software improves this is a diminishing concern.

If you would like to know the exact MIME encodings and message structure used by CustomMailer, see the answer to this question in the HTML Mail section of "Frequently Asked Questions".