rails/rails — pull request #8044 by nateberkopec (2012-10-27 18:56:44+00:00)
Title: Explicit multipart messages respect :parts_order

My original issue was #7978. Our app's emails were showing up in Gmail as plain text only, and I couldn't figure out why. I checked the raw text being sent, and confirmed both HTML and plaintext parts were in there.

However, what I wasn't aware of was this little line in RFC 2046:
>In general, user agents that compose "multipart/alternative" entities
must place the body parts in increasing order of preference, that is,
with the preferred format last. [..] Receiving user agents should pick and display the last format
they are capable of displaying.

Aha! So I checked the order of my mime parts, and, lo and behold, the plaintext part was being sent last! So Gmail was following the spec correctly - it was displaying the last format it was capable of displaying. (Side note: other mail clients seem to display HTML regardless).

Now, what the heck was actually setting this order? I read through the ActionMailer documentation and discovered the `[:parts_order]` option. Great! All I have to do is set this and it'll work fine. Nope. After about a day worth of digging and frustration, I discovered that passing a block to `mail` sets the parts order to the same order as the block!

This pull request changes `mail` to respect `:parts_order` regardless of the order of any block passed into `mail`. I decided this change, rather than just clarifying the documentation, was appropriate for several reasons:
* It wasn't clear what should happen when `:parts_order` and the order of the block conflicted. Which should take precedence?
* Setting the mime part order in two places seemed unnecessarily confusing.
* When an email is multipart, I can think of few reasons why html would *not* be the preferred format. It seems too easy to accidentally send an email you *think* will show up as HTML but actually will be plaintext (this is what happened to me). `:parts_order` already sets a sensible default (html last), so let's make it difficult to unintentionally mess up this setting.
* In ActionController, the convention when writing an explicit block is put `format.html` first in the order of possible formats. This is how most examples/documentation is written. In ActionMailer, in order for HTML to actually display in an end user's mail client, you have to do the opposite. Flipping this convention in ActionMailer seems unneccessary.

Thanks for considering this change. I lost about a day or two figuring this one out, just want to prevent anyone from having