Contrib.social

Provide full to/cc/bcc email configuration

Open on Drupal.org →
Created on 6 April 2022, over 2 years ago
Updated 4 May 2024, 5 months ago

Problem/Motivation

This module has a fixed method of sending emails: all outgoing mail is via the 'bcc' header, except for the site email, which appears under 'to'. However, 'to' is empty if the "Disable the site email" configuration is checked. This is overly limiting in how site managers can format outgoing emails. Because the use of 'bcc' is not well documented and 'bcc' recipients are not visible in emails that are sent out, it can lead to confusion by users of the module. But perhaps the biggest problem is that the empty 'to' field when "Disable site email address" is checked can lead to mail being refused and dropped (not just flagged as spam).

There are examples of all these scenarios in the issue queue. Recently, I experienced email failures when our host changed email services to AWS SES, which invokes a "no-empty-to-field" rule, and it took a fair amount of debugging and collaboration with different departments and vendors to work out the source of the issue.

A number of issues have been created to address this problem in various ways. Each tackles the problem in a different way, and in the process, ends up setting limits and hard-coding other behaviors that site managers may not want (often presumably in the name of keeping changes and the patch simple). But if we are going to solve the problem in a robust way that meets most peoples' needs, we should consider a more comprehensive update that grants the ability to specify to/cc/bcc headers for all outgoing mail recipients that this module handles.

This issue proposes such a comprehensive solution. Working code is available for review and critique, but requires additional work such as tests.

Proposed resolution

We should give site managers the ability to decide how each of the configurable email addresses (author, site email, role based users, ad hoc) should be sorted into each of the available email address headers (to, cc, bcc). Each of these headers has a reason for being used, and it would improve the module to give people the ability to choose those that best meet their needs, even without the empty-to failure issue.

For each recipient configuration, this proposal recommends:

  • Author: convert current boolean yes/no that puts email in 'bcc' into a series of options that includes a no-email option: to, cc, bcc, none.
  • Site email: convert current negative-assertion boolean ("Disable the site email?" yes/no) hard-coded to the 'to' header into a series of options that includes a no-email option: to, cc, bcc, none.
  • Role emails: keep the existing role selection configuration, but add a "Role Header" configuration that allows the site manager to choose to send the role-based emails via to, cc, or bcc. (Configuring headers on a per-role basis would be possible, but considerably more complex, so out of scope for this project.)
  • Ad hoc emails: convert the single text field that currently places all recipients under the 'bcc' header into separate fields for each of the to, cc and bcc options, allowing a mix of headers to be used for ad hoc email addresses.

Completed tasks

These steps have been preliminarily completed, though all are open to review and comment.

  • Update config properties, adding new ones and deprecating old ones in schema and the ContentModerationNotification class annotation.
  • Update the ContentModerationNotification class properties and methods to accommodate the new configs.
  • Update the edit form (ContentModerationNotificationsFormBase) to handle the new properties and remove deprecated ones.
  • Update the ContentModerationNotificationsListBuilder controller to display the new properties.
  • Update Notification::sendNotification() to process the new configs and assign them to the proper email headers.
  • Create an update hook that converts existing notification configurations to use the new config properties in a way that retains the to/bcc recipient header lists.

Remaining tasks

  • Update tests: deprecated and removed config properties cause some tests to now fail. Tests should be updated to utilize the new properties.
  • New tests should be added to cover the new properties and logic.
  • Edit form: group the form elements related to setting recipients visually and provide overall help text. Provide guidance (importance of at least one 'to' recipient) and reduce redundancy in some field help text (such as info on tokens and Twig processing).
  • Edit form Role Headers field: make field appear conditionally only when at least one role is checked.

Related Issues

  • ✨ Option to put email addresses in To: instead of in Bcc: Needs work adds a new "To: instead of Bcc:" configuration parameter that solves the empty 'to' field problem by moving all 'bcc' emails to the 'to' field. In the process, it renders the "Disable site email address" field irrelevant if the new field is checked. No option is available to add recipients to 'cc' or 'bcc'.
  • #3208996: "Disable site mail" feature not compatible with PHP Mailer library → is similar to the previous issue, but instead of being configurable, it hard-codes the move of all 'bcc' recipients to 'to'.
  • #2946360: Make the recipient configurable → adds a "Recipient" configuration parameter that is explicitly for managing the 'to' field. Patch appears to be from before the "Disable the site email address" field was added. Instead, the 'to' field is set to this new Recipient property, if set, otherwise uses the site email address.
  • #3159790: Email the author not working → moves the author email to the 'to' field (if send mail to author is checked), overriding/replacing the site email (if present) and removes the author email from the 'bcc' headers list. This behavior is enforced for all and not configurable.
  • 🌱 Support Twig, TO, CC, BCC, FROM, REPLY-TO, SUBJECT, Message, Abort, Debugging and Tips Active is an even more ambitious issue than this one that includes configurable to/cc/bcc as one of its goals. This approach appears to use complex Twig template logic to handle assignment of recipients into to/cc/bcc headers. Role-assigned emails remain hard-coded to 'bcc'.

The first four issues here would be resolved by this issue's approach, though in different (and more flexible) ways than each issue proposes. This issue's approach would conflict with the last meta-issue. If this issue's approach is implemented, the last issue above could perhaps be split into separate child issues to tackle the additional requests separately.

User interface changes

Config property changes require updates to the list of configured notifications (/admin/config/workflow/notifications) and the notification configuration edit form. (/admin/config/workflow/notifications/manage/{notification}). Preliminary work on this has been completed, but the edit form could use some additional polish.

API changes

This fork/proposal may impact current users of hook_content_moderation_notification_mail_data_alter due to changed email processing logic. Work has already been done to preserve this hook's original functionality. An update hook is also required to migrate existing configurations to the new configuration properties, and such a hook has been developed that is available for review and testing.

Data model changes

To avoid changing existing configuration property typing (e.g., boolean to string), this issue removes deprecated configuration properties and adds new ones that provide greater configuration possibilities. The schema and annotation have been updated for these changes, and the ContentModerationNotification class has been updated to accommodate the new properties and associated methods.

Incidental changes

  • Token/Twig handling is not consistent, but could be. Current stable (8.x-3.3) has token processing in the subject and message fields. Dev (8.x-3.x) recently added Twig template parsing to these fields as well as the ad hoc field #2953489: Add Twig support in Subject, Email, and Message fields → . This means that the ad hoc field is inconsistent with subject and message. Two issues asking for this functionality in the ad hoc field have been closed on the presumption that Twig offers the same functionality, but responses indicate users still want basic tokens. #2952409: Tokens in AdHoc address field → & #3088428: Support tokens in adhoc To email addresses → This fork/project unifies token and Twig template processing across all text input fields (specifically adding token processing to the ad hoc fields).
  • This module's hook_content_moderation_notification_mail_data_alter is awkward and limited because the hook fires before logic is applied that sends all $data['to'] (recipients) to 'bcc', so you can't (easily) override this behavior. Some extra logic has been applied to this fork/project to try to preserve the hook's original behavior for those who have implemented it already. However, Drupal core's hook_mail_alter provides greater flexibility because it fires after the module's logic has completed, allowing one full control of any of the outgoing email's headers. Some language has been added to deprecate the old hook and to suggest hook_mail_alter() instead.
✨ Feature request
Status

Needs work

Version

3.0

Component

Code

Created by

🇺🇸United States daletrexel Minnesota, USA

Live updates comments and jobs are added and updated live.
  • Needs tests

    The change is currently missing an automated test that fails when run with the original code, and succeeds when the bug has been fixed.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment 12 months ago →
    🇬🇧United Kingdom PQ

    Just a note that the current solution here seems to break when used with the sendgrid_integration module which validates the email addresses of the bcc and cc headers. If empty it throws an error.

    It might be resolved by changing this:

          $data['to'] = implode(',', $recipients['to']);
      $data['params']['headers']['Cc'] = implode(',', $recipients['cc']);
      $data['params']['headers']['Bcc'] = implode(',', $recipients['bcc']);

    (in src/Notification.php line ~213) to something like:

          $data['to'] = implode(',', $recipients['to']);
      if (!empty($recipients['cc'])) {
        $data['params']['headers']['Cc'] = implode(',', $recipients['cc']);
      }
      if (!empty($recipients['bcc'])) {
        $data['params']['headers']['Bcc'] = implode(',', $recipients['bcc']);
      }
  • Comment 8 months ago →
    🇨🇭Switzerland zilloww

    Zilloww → changed the visibility of the branch 3273627-toccbcc-email-config to hidden.

  • Comment 8 months ago →
    🇨🇭Switzerland zilloww

    Zilloww → changed the visibility of the branch 3273627-toccbcc-email-config to active.

  • Comment 5 months ago →
    🇪🇸Spain aleix

    Just reporting that without the 'to' sendgrid transport that comes with symfony_mailer cannot work.

    The to array is required for all personalization objects, and must have at least one email object with a valid email address.

    `http://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/errors.html#messa...`

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024