commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Morten Hattesen (JIRA)" <>
Subject [jira] Commented: (EMAIL-65) MIME layout generated by HtmlEmail causes trouble
Date Wed, 14 Mar 2007 13:00:20 GMT


Morten Hattesen commented on EMAIL-65:

I have a couple of comments...

The API contract for HtmlEmail
states that ...
"Either the text or HTML can be omitted, in which case the "main" part of the multipart becomes
whichever is supplied rather than a multipart/alternative."
... which is in violation with the currently generated MIME structure (see example 1), which
builds a multipart/related container, even though no "related" (i.e. embedded inline) MIME
parts are available.

If HtmlEmail does not support generating messages with a single text/plain MIME part, by gracefully
degrading to content resembling that generated by SimpleEmail/MultiPartEmail, then it should
throw an IllegalStateException (possibly wrapped in an EmailException), rather than generating
a fundamentally flawed MIME structure.

With regards to my example 3, the argument is that the currently generated MIME structure,
with attachments inside a multipart/related container does not follow MIME recommendations
nor does it resemble the structure generated by other popular smtp clients. Attachments should
be contained in a multipart/mixed container. 
+  multipart/mixed - "The "mixed" subtype
of "multipart" is intended for use when the body parts are independent and need to be bundled
in a particular order."
+  multipart/related - "The Multipart/Related content-type
provides a common mechanism for representing objects that are aggregates of related MIME body
My interpretation of the above standards is that multipart/related should be used for mail
body with inline parts, which should be treated as a whole (compound), whereas multipart/mixed
is used for parts which may be used in isolation (mail body and attachments). If we are forced
to use only one MIME type for both situations, it should be multipart/mixed.

I may not be able to provide concrete proof of email clients that will choke on the current
MIME structure (although I will do my best to do so), but that should not be used as an excuse
to continue to generate flawed MIME structure. I do, however recognise the need for thorough
testing prior to any major change being made, as well as the "if it ain't broke, don't fix
it" paradigm.

My final argument is, that since the principal role of commons-email is to provide a simple
API facade on top of the complex JavaMail API, it should always generate MIME structures that
adapts to the actual contents. In other words, the client-programmer need not concern himself
with having to choose a "lesser" Email subclass just because a certain email instance does
not contain one of the allowed content types. In other words, I feel that the only reason
not to always choose HtmlEmail to generate emails, is when the client programmer never requires
facilities offered by HtmlEmail, and wishes a simpler API (MultiPartEmail or SimpleEmail).
If this structure should be reflected by the type hierarch of Email, the hierarchy should
look like so:
Email (might as well be made abstract)
  +-- SimpleEmail
    +-- MultiPartEmail
      +-- HtmlEmail

- mind you, to maintain API backwards compatability, I am in no way suggesting such a type
hierarchy change for version 1.x

I will be happy to contribute code, and/or testing effort on this issue, please let me know
if I can be of any assistance.

> MIME layout generated by HtmlEmail causes trouble
> -------------------------------------------------
>                 Key: EMAIL-65
>                 URL:
>             Project: Commons Email
>          Issue Type: Bug
>    Affects Versions: 1.0
>            Reporter: Morten Hattesen
>             Fix For: 1.1
> Previous bugs (e.g. ) raised against commons-email
version 1.0 have complained about Outlook not being able to properly display multipart emails
generated by HtmlEmail. While this issue is resolved as of rev 510708, I believe there a several
issues regarding MIME layout, that still cause trouble to email clients.
> In the current codebase, a multipart email containing: plaintext part, html part, inline
images and attachments, is constructed (to the best of my knowledge) with a MIME layout like
> Generated by HtmlEmail. Contains parts: plaintext, html, embedded inline img, attach
> 1 multipart/related
> 1.1 multipart/alternative
> 1.1.1 text/plain (the plaintext content) 
> 1.1.2 text/html (the html content with cid: references to embedded images) 
> 1.2+ */* (attachment) 
> 1.3+ image/* (embedded image, referenced by 1.1.2) 
> ("+" above indicates that multiple (1..n) parts may be included)
> The above structure may cause email clients to display embedded images as attachments,
even though they are semantically part of the text/html content.
> Furthermore, the current codebase (as documented in the HtmlEmail.setMsg() JavaDoc) synthesizes
a html part by <pre>...</pre> wrapping the plaintext part, thus generating a bloated
(double size) message, for no apparent reason. In my opinion, HtmlEmail should degrade to
the mime layout of Email, if no html part is available.
> Proposed MIME layout
> ------------------------------
> To the best of my knowledge, a multipart email containing: plaintext part, html part,
inline images and attachments, should be constructed like so:
> 1. multipart/mixed
> 1.1 multipart/related
> 1.1.1 multipart/alternative
> text/plain (the plaintext content)
> text/html (the HTML content with cid: references to embedded images)
> 1.1.2+ image/* (embedded image, referenced by
> 1.2+ */* (attachment)
> The following simplifications of the above structure may be applied:
> a. If no embedded images are included, items 1.1.2+ and 1.1 are removed.
> b. if no text/html part is included, items and 1.1.1 are removed
> c. if no attachments are included, items 1.2+ and 1 are removed
> Incidentially, this MIME layout is used by GMail, which is an indication that it is the
"proper" way.
> I seriously believe that this issue should be investigated and resolved, if at all possible,
as part of version 1.1.
> I may be able to supply a patch to in the April/May 2007 timeframe, but
I am not prepared to put any body parts on the block on that one ;-)
> I welcome any comments!
> Morten Hattesen
> References:
> See for additional information and references

This message is automatically generated by JIRA.
You can reply to this email to add a comment to the issue online.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message