HTML E-Mails

[aaroncampbell]

Wojtek worked on the Enhanced E-Mails project for GSoC this summer. It's definitely something that would be nice to have in core. The plugin already exists in the repository - ​Enhanced Emails. There are still some things that need to be cleaned up in the code, but it works pretty well.

I'm hoping we can clean it up, test it, and get it in core.

This is in the 3.3 scope ​http://wpdevel.wordpress.com/2011/07/27/wordpress-3-3-proposed-scope/ (in Mixed Bag), so a patch for core would be welcome.

fixed eemails references

This patch was not thoroughly and is still a work in progress. It merges the "enhanced emails" project with current trunk and fixes naming and template problems.

Logo added.

TODO:

• Merge admin options and add the "if use_html"
• Testing!

Assigning to myself for review.

Per ​IRC discussion, moving to 3.4.

This patch still has a bug. The variable $phpmailer->AltBody is not initialized. If you send an html email and then a plain email, the second email gets the first email's attachment. This can be a security problem if sending one email with privileged content, followed by another email with public information. Suggest in wp_mail():

wp-includes/pluggable.php

	$phpmailer->ClearCCs();
	$phpmailer->ClearCustomHeaders();
	$phpmailer->ClearReplyTos();

+	$phpmailer->Body= '';
+	$phpmailer->AltBody= '';

	// From email and name
	// If we don't have a name from the input headers
	if ( !isset( $from_name ) )

I'd also suggest clearing $phpmailer at the end of the function wp_mail(). It could be holding some lengthy strings. Best would be a clear method for $phpmailer. But the code above is a minimal fix.

Are there any plans to integrate this? If this needs updating, I'll take ownership and get it updated.

Well I was willing to keep going with the project, but westi asked me to wait until he reviews it. Since it's clearly not a top priority for core developers, maybe we could wrap this up by ourselves and deliver something ready to merge ith the core without lots of improvements?

Sounds like it's time to ping westi some more. :)

Are there any outstanding issues to work on (apart from wiping $phpmailer afterwards)?

AFAIR I did, in Dec ;)

Well one thing which was my main concern, is the way templates are handled. Most of the current plugins do it via output buffering and just having the template structure pretty similiar to the standard themes. However, it was suggested to me during development that the email contents should be kept in a variable (<read in Mr. Mackey's voice>because output buffering is bad, mkay?) - it's kind of a serious issue, because the variable solution is ugly and apparently output buffering is out of the table

Ah yeah, I had the same issue with a project I was working on (which is actually where the multipart wp_mail comes from).

We ended up going with raw HTML/text templates, and using substitution (%TITLE%, e.g.) from memory. We tried using output buffering, but that can introduce extra problems, and it's not a good practise regardless.

I'm not sure if that would quite work with these templates though. Anything that has a loop won't really work, unless you use a subtemplate and handle the looping separately.

Raw files with variable substitution are not a bad idea, but probably not for this project - I wanted to make them behave almost exactly like the standard templates would.

Agreed. The only thing I can think of is having the templates looking something like:

<?php
$content = <<<EOL
This is a template.

Here is a $variable
EOL;

$content .= 'Something else';

But then we end up with magical naming, so I'm not a big fan of that either. The only other thing I can think of is using a filter for all of this instead, but that has problems too. I think that's probably the most WordPress-y way though.

I just pinged @westi.

I've been thinking about this a lot so sorry for not getting back to you sooner and for the length of this comment.

So far I have seen a solution which I feel comfortable with in core so I thought it was probably best to set out some goals as I see them for the first version of HTML emails in core and then we can discuss how best to move forward.

1 Update WordPress so that all the emails it sends have a HTML version.
2 Provide an API that makes it really easy for plugins to send HTML emails.
3 Provide an API that makes it really easy for themes to customise the styling of the emails to integrate with a site design.

I think the key issue here is how can we make (2) and (3) as simple as possible and I think there are a few options/pieces to the puzzle:

1 How much should be templates versus "magic" - i.e. Do we need to have HTML versions of every email body we send or can we just auto-tag the text using autop / a simple markup language.
2 Should we use php templates which print the output and output buffering or functions which return the HTML.
3 Can the emails be made to be themable enough by just letting the header/footer be customisable

I think that however deep we go into templating to make this truly extendable by plugins and overridable by themes we should start small and then build up as we find problems issues we need to address and discuss and address each one.

As such I think the following phased approach would be a good way to address HTML emails for core:

Phase 1 - This may be starting too small but also should be something someone could pull together in a couple of hours as a proof-of-not-a-concept ;)

Create an api function wp_html_mail( $to, $subject, $message, $headers = '', $attachments = array() ) which mirrors the API of wp_mail() but takes the message and wraps in up into a nice HTML blanket.
This api has filters which allow a theme to do simple child theming of the emails:

• Replace the CSS that we output in the header of the email - I believe based on my understanding of the limits of HTML emails this will allow for
• Replace the logo used in the email to identify the site.

The header and footer html would not be customisable.

Then we can review what each of the emails core generates looks like with this simple api and see if we are happy or need to move on to Phase 2

Phase 2 - Make things more flexible, extensible.

Slowly extend the api to support templates, investigating the following:

• Can we make a solely function based template system where we have default functions in core and themes can replace them (either through a registration API or like pluggable functions)?
• Can we make an output buffering based solution not be ugly?
• Should we implement a simplified templating language?

I think when we review these we will find that on balance an output buffering based template system is best because it gives theme developers the most familiar experience and gives them full control. However, I would still like to keep simplicity in mind and if we can come up with a lightly templated solution which doesn't give full control over the content area of the emails - so we can keep a common format and just makes it easier to change the general style/header/footer and for plugins to make use of this style/header/footer with there own custom bodies then we may have found the perfect middle ground ;)

I know this sounds a lot like starting from scratch but I don't see it that way we have got a lot of excellent work already done dealing with the intricacies of getting HTML emails that look nice in email clients and the discussion now is more how we can adapt these to make them integrate into core in the best way.

It would be great if we could all get together in IRC early next week to discuss - I'm around most week days 9am-5pm UTC.

Replying to westi:

1. How much should be templates versus "magic" - i.e. Do we need to have HTML versions of every email body we send or can we just auto-tag the text using autop / a simple markup language.

This is actually harder than it seems, but it is possible. The easiest way is to use a HTML-to-Markdown converter, since Markdown is based on email formatting.

In any case, if we want to even think about including full post content in text emails, we'll need this. Personally, the excerpt is enough for my needs, but I can see that being different for other people. It depends on what we'll want in core.

3. Can the emails be made to be themable enough by just letting the header/footer be customisable

Given the state of CSS support in email clients, no. Unfortunately, you often need to be able to use inline styling (​Gmail does not support anything but inline styling, for example).

Phase 1 - This may be starting too small but also should be something someone could pull together in a couple of hours as a proof-of-not-a-concept ;)

Create an api function wp_html_mail( $to, $subject, $message, $headers = '', $attachments = array() ) which mirrors the API of wp_mail() but takes the message and wraps in up into a nice HTML blanket.

What would be the advantage of this over the current proposed solution? (That is, overloading wp_mail's body parameter)

I think the filtering would have to be done pre-wp_mail, wherever it's called, given the different formatting of all the different emails that are sent.

This api has filters which allow a theme to do simple child theming of the emails:

• Replace the CSS that we output in the header of the email - I believe based on my understanding of the limits of HTML emails this will allow for

As I noted above, email client support isn't good enough to be able to do this, unfortunately. One possibility is a per-element filter, but that seems somewhat crazy to me. I think being able to replace the whole thing is going to be necessity.

• Should we implement a simplified templating language?

I think when we review these we will find that on balance an output buffering based template system is best because it gives theme developers the most familiar experience and gives them full control.

I have to agree. While output buffering is fairly ugly from our perspective, it's much nicer from a theming perspective. To me, a templating language is not WordPress-y enough, and I think it would likely be a bit confusing.

It would be great if we could all get together in IRC early next week to discuss - I'm around most week days 9am-5pm UTC.

I'm around most days from 3am-5pm UTC, and I can be on IRC for all of that time if I remember to open my client. :)

I'm around most of the days 8(9)am-4pm UTC. During the next few days I'm in London so I won't be able to participate in any chats before Tuesday

Would love to see this implemented into the core for 3.5. Sending multi-part emails that are compatible with all email clients is essential for many businesses and this fix would correct what is lacking currently in the wp_mail function.

I can help out and take part in discussions on this ticket, but since my right hand is broken and will remain in a cast for the next four weeks at least, I won't be able to help much with the coding part (maybe in September).