Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: notification unsubscribe & email overhaul with HTML multipart #3872

Merged
merged 61 commits into from
Sep 29, 2023

Conversation

imorland
Copy link
Member

@imorland imorland commented Aug 19, 2023

Removals, changes & additions

SendRawEmailJob is removed, and replaced with SendInformationalEmailJob.

Usage example:

$queue->push(new SendInformationalEmailJob(email: '[email protected]', subject: 'emailSubject', forumTitle: 'forumTitle', bodyTitle: 'informationHeader'));

Outgoing email format

image

By setting the mail_format to text, you're instructing Flarum to only send emails in the plain text format, disregarding the HTML version and multipart option. Adjust this setting according to your needs, but it is recommended to leave it at it's default.

Notification templates

Flarum now has two types of notifications/emails. Notification and Informational. Informational emails are things like, password confirm, test, etc. Basically an email that does not require (or should not have) an unsubscribe link and are classified as "essential" or "service" mail.

For all other emails, this should probably fall into the Notification type. These notifications automatically generate an unsubscribe link and this is rendered in the footer of the email (both HTML and plain).

For this reason, when constructing blade templates for emails, you should extend one of the base types:

HTML
  • @extends('flarum.forum::email.html.notification.base')
  • @extends('flarum.forum::email.html.information.base')

When rendering content and/or preview content in a HTML template, it must be wrapped in the utility $formatter->convert($yourContent) For example:

{!! $formatter->convert($translator->trans('my_key')) !!}

or, for a Post object:

{!! $blueprint->formatContent() !!}
Plain
  • @extends('flarum.forum::email.plain.notification.base')
  • @extends('flarum.forum::email.plain.information.base')

Both templates allow for sectioned data to be rendered. It is no longer required to include the user greeting, this is now contained in a translation key core.email.greeting, for example "Hey username".

@section('content')
{YOUR_CONTENT_HERE}
@endsection
@section('contentPreview')
{YOUR_CONTENT_HERE}
@endsection

contentPreview is optional, if your blade template does not provide it, nothing will be rendered in it's template area. content is always required.

Emails now also have a "signoff" section. Here, the translation key core.email.signoff by default will render "The {YOUR_FORUM_NAME} team".

Should you wish to disable either the greeting or signoff, this can be done on a template by template method:

@extends('flarum.forum::email.html.notification.base', ['greeting' => false, 'signoff' => false])


  • Create a new model UnsubsribeToken
  • Modify MailableInterface so that notification blueprints return both plain and html views
  • Create base blade templates for both plain and html for all notification emails to extend.
  • One click unsubscribe option for the specific notification type
  • Redesign the notification content
  • Allow admins to specify multipart, plain or html emails from the forum
  • Generic multipart template in place of the old raw emails (email test, forgot password, etc)
Screenshots

Example informational email (email test):
image

Example notification email (desktop):
image

After clicking to unsubscribe from a notification type, the user is asked to confirm:
image

...

Changes:
  • Refactored Email Templates: All notification emails now have a consistent base structure, making it easier for extensions to create or modify their notifications.
  • HTML Email Support: In addition to the existing plain text email templates, support for HTML email templates has been added. This provides a richer and more visually appealing experience for users. Emails are now sent multipart, with both plain text and html versions.
  • Added Unsubscription: Users can now easily unsubscribe from specific types of notifications with a direct link in the email, enhancing user experience and reducing unwanted emails.

Copy link
Member

@askvortsov1 askvortsov1 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this a lot, great job! My only thought: maybe we should have the unsubscribe controller redirect to the settings page, with a payload in the URL that would trigger an alert / popup / etc?

@imorland
Copy link
Member Author

I like this a lot, great job! My only thought: maybe we should have the unsubscribe controller redirect to the settings page, with a payload in the URL that would trigger an alert / popup / etc?

I did consider that at one point, however that would also require the user to be either logged in, or be bounced thru an auth flow before bing able to present their settings.

My understanding for Unsubscribe-List is that it should ideally be 1-click. Perhaps we can do this by using the one-time token already generated for the unsubscribe to log the user in? 🤔 Then again, that would also be a security risk, as anyone with that email would then be able to access the account (if the token has not already been used).

@askvortsov1
Copy link
Member

That's a good point. I think "unsubscribe on click + link to settings page" is a good compromise.

Instead of unsubscribing on the GET request, maybe that page should be a form (autosubmitted via JS), that pings a POST endpoint?

@imorland
Copy link
Member Author

Instead of unsubscribing on the GET request, maybe that page should be a form (autosubmitted via JS), that pings a POST endpoint?

And if JS is disabled/not available in the email client webview/whatever?

@askvortsov1
Copy link
Member

Instead of unsubscribing on the GET request, maybe that page should be a form (autosubmitted via JS), that pings a POST endpoint?

And if JS is disabled/not available in the email client webview/whatever?

Then show a button. Most unsubscribe links I've experience ask you to click a button to confirm; the annoying ones are where you need to click a bunch of checkboxes. What I'm proposing is pretty much what's discussed in the comment thread started by @luceos

@imorland
Copy link
Member Author

Yeah, sorry I was having a "moment" 🙈

I'm already working on this, should be ready shortly

@imorland imorland changed the title feat: notification unsubscribe links & HTML template support WIP feat: notification unsubscribe links & HTML template support Aug 21, 2023
@imorland imorland changed the title WIP feat: notification unsubscribe links & HTML template support WIP feat: notification unsubscribe & HTML emails Aug 21, 2023
@imorland imorland requested a review from SychO9 September 28, 2023 16:00
@SychO9 SychO9 merged commit 412cfaf into 2.x Sep 29, 2023
22 checks passed
@SychO9 SychO9 deleted the im/unsubscribe-links branch September 29, 2023 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants