HTML email notifications
Another major feature for CAC 1.5.
Ray, I know you've done some work on HTML emails in the past, so I'm assigning to you.
In short: our emails are filled with links, which can be a bit overwhelming. By having optional HTML-formatted emails, we'll have the ability to make things much richer and more attractive, and hopefully increase user engagement.
Some initial thoughts:
- Should provide plaintext alongside of HTML, for clients that have a plaintext preference (like my client)
- Should also have a per-user preference setting for HTML vs plaintext
- Can we handle inline assets, esp images? What about when they're protected, as in a private group?
- Branding: Do we send our logo? As an attachment or hotlinked from the production site?
- Design: what does it look like?
- Must work seamlessly with RBE
- Can we leverage existing plugins? Do we need to write something new? Pass something upstream to BP? Include something in Commons In A Box?
#1 Updated by Raymond Hoh almost 9 years ago
I've answered most of the points here:
I'm thinking of using WP Better Emails. The functionality has almost everything we want.
The points that need addressing from your description are:
Can we handle inline assets, esp images? What about when they're protected, as in a private group?
Need to test this more, but if the content of the item already uses HTML (<img> tags, etc), then I believe we should be fine. If it uses some pseudo syntax like Markdown, then no and we'd need to include such a parser.
What other inline assets are we talking about other than links, images, bullet points?
As for being "protected in a private group", we don't have the upload API completed yet. If you're talking about using WP Better Emails in conjunction with the Forum Attachments plugin that CAC currently uses, then I'm not sure at the moment. We'd probably need to add some hooks to WP Better Emails so we could inject stuff into the email contents.
Must work seamlessly with RBE
It works at the moment, but the HTML template formatting gets in the way of the "reply above this line" marker in RBE. WP Better Emails needs tweaking to better support plain-text emails.
#2 Updated by Raymond Hoh over 8 years ago
Boone, just to update this thread.
- I've forked the WP Better EMails (WPBE) plugin here.
- And have added a pull request here.
- I'm just waiting for the author to merge the changes in.
- My companion plugin - WP Better Emails for BuddyPress - has been updated so HTML content is supported
- Requires my WP Better Emails fork in the meantime.
- Only @mention emails and activity reply emails are supported for now. The plan is to expand this to the BP Group Email Subscription plugin.
- I've had to work around some BuddyPress core shortcomings. For one, BP currently strips HTML tags for activity email content before sending and we want to support HTML tags.
- Basically any tag supported in bp_activity_filter_kses() - inline images and links - will work. We can expand this later if desired.
- Plain-text emails are also better formatted as the HTML is converted to basic Markdown for inline images and links
- Download my WP Better Emails fork and my WPBE for BP plugin from above
- If you're testing with RBE, download the latest version as well.
- Activate both plugins and in the WP dashboard, navigate to "Settings > WP Better Emails". On this page, you can format the HTML template and the plain-text template for emails.
- In BuddyPress, mention someone and in the body of the contents add some <img> and <a> tags.
- The email should render in HTML and should also degrade very well in plain-text as those tags are converted over to Markdown.
Note: None of these changes are added to the CAC repo yet.
Let me know what you think after you've had a moment to test.
#6 Updated by Boone Gorges over 7 years ago
- Status changed from Assigned to Testing Required
Sorry for the delay on this. I've added the plugins to the 1.6.x branch https://github.com/castiron/cac/commit/6b661e6a511360a72dc9b095261fada9d3f9335e https://github.com/castiron/cac/commit/fe42e9d72d53c320d709d9c1bb19bf2da4f21db9 and they're ready to test on cdev.
Initial impressions and questions for Ray:
- I know you've basically copied over BP's core notification text for eg use_html_for_at_message(), so maybe these comments are preliminary. But this section of the message is obviously where we can do a good deal of our HTML-ification. In particular, "To view and respond to the message, log in and visit: URL" can just become "View", which is a link. Etc.
- Maybe we could also think about breaking the "To disable these notifications..." and some of the boilerplate from BPGES into separate wrapper methods. These parts of the message feel more like footer-fodder to me than content, so it would be nice to separate them out (and also to reduce duplication).
- I tried using reply by email, but got the email returned - "could not find the text". Maybe something has changed in bp-reply-by-email since this was originally posted?
For the rest of the team:
Play around (see http://redmine.gc.cuny.edu/issues/2350#note-2 on how to test) and see what you think. The team discussion will surround the question of what these emails should look like. Do we include the Commons logo (good for branding, maybe bad for people's bandwidth and a bit rude)? How do we think about reformatting what is currently plaintext? Eg, convert existing links to a row like this: View | Reply | Unsubscribe. Are there other formatting issues - fonts, colors, layout, etc?
#8 Updated by Matt Gold over 7 years ago
Boone - regarding your questions:
1. Yes, we should include a logo in the footer of the email. I'm going to create a separate ticket, because Michael will work on this
2. Yes, for the HTML email, we should convert lines that currently appear like this:
To view or reply to this topic, go to:
Should be "View and Reply," with the link embedded
3. For the plaintext version, where we probably need to include the full URL, Micki is wondering whether we can use cuny.is to create shorter links
4. For colors, layout, fonts -- let's see what Better WP Emails has by default, and then tweak it by referencing the MailChimp email template. Micki will upload a zip file containing the template.
#11 Updated by Raymond Hoh over 7 years ago
Sorry for the late reply. I never received Boone's update from March 5th in my inbox for some reason and got Matt's recent email over the weekend.
Going to reply to Boone's comments below:
I know you've basically copied over BP's core notification text for eg use_html_for_at_message(), so maybe these comments are preliminary. But this section of the message is obviously where we can do a good deal of our HTML-ification. In particular, "To view and respond to the message, log in and visit: URL" can just become "View", which is a link. Etc.
Agreed. In use_html_for_at_message(), we can basically write our own email content as HTML. I just didn't do this in the initial version of the WP Better Emails for BP plugin.
HTML content isn't supported for BPGES yet. The content is currently converted to plain-text because BPGES strips out all HTML tags. I'll probably have to add a filter so we can grab the content before sending.
Maybe we could also think about breaking the "To disable these notifications..." and some of the boilerplate from BPGES into separate wrapper methods. These parts of the message feel more like footer-fodder to me than content, so it would be nice to separate them out (and also to reduce duplication).
For sure it feels like duplication, but by removing the GES footer stuff, are we going to add it back into the HTML template somewhere? Right now, we can only manipulate the email content and not the HTML template.
I tried using reply by email, but got the email returned - "could not find the text". Maybe something has changed in bp-reply-by-email since this was originally posted?
Boone, it looks like your problem is related to CAC having the ability to reply to individual activity comments. This is a bug that was addressed in bp-default, but not with CAC. I've just pushed a commit that fixes this.
I've also fixed some other things with RBE and WP Better Emails in commit 2227f1d4de
Just pulled these changes onto cdev and tested and it looks like it works now:
Some other issues that will need to be solved:
- Make BPGES compatible with WP Better Emails
- RBE currently uses the plain-text email as the content and posts it. It does not use the HTML reply at the moment due to parsing and formatting issues. So if someone replies to RBE in HTML, it will only post the plain-text version.
#12 Updated by Boone Gorges over 7 years ago
Excellent. Thanks for your work on this so far, Ray. I'm going to start working my way through this issue, because we want to close our dev window on Monday for 1.6, and I'd like to see this go in.
First step: GES now does all its cleanup, including strip_tags() and html_entity_decode(), in callbacks that can be removed with remove_filter(): https://github.com/boonebgorges/buddypress-group-email-subscription/commit/225c88b83e9b4f6e81d9b436561e7517be9a55d2
#13 Updated by Boone Gorges over 7 years ago
As is usually the case, this is turning out to be more work than I'd thought :) I've begun to translate all the various emails sent by BP into HTML, and I've finished most of the native BP emails. See https://github.com/cuny-academic-commons/wp-better-emails-for-bp. As Ray notes, the BPGES-generated group emails (which are probably the most important ones for the Commons) are more complicated. The way GES builds the emails means that lots of front- and back-matter is added, which needs to be filtered separately.
Ray, I've started work on this aspect. See the latest master of GES and this changeset: https://github.com/cuny-academic-commons/wp-better-emails-for-bp/commit/954e34458a573a04d5a54a921cd0cb93357725e5 I think that we can take care of all the GES-specific formatting in a single wrapper that does some preg_replace()ing, but it needs some work. If you have time in the next day or two, maybe you could try to take a look? I feel like if we get this aspect straightened out, the rest of the work required will be fairly straightforward.
#15 Updated by Boone Gorges over 7 years ago
- Status changed from Assigned to Testing Required
- Assignee changed from Raymond Hoh to Chris Stein
I think we've got a good version of this ready to test. Ray, thanks for your work on it.
All emails from the WP installation are now piped through an HTML wrapper. Emails that originate with BP or BP Group Email Subscription (such as friend request emails or new forum post emails) have been reformatted to take advantage of the ability to link. HTML content within any of these activity types should be passed through in the email.
At the moment, the styling in the email itself is very minimal. We can make very small changes, if necessary, but it's too late for us to make major design changes to the email template and still make our deadline. IMO, this is fine for v1.6 - these emails are far, far better than what we're currently sending.
I'm assigning this to Chris to do some preliminary testing. Primarily, what I want is a sign-off from him or from Matt that the way the emails look is fine for 1.6. I'm not comfortable passing this feature along to the community team for more extensive testing (in various email clients, etc) if large changes are pending.