Email Attachment Helper

This is a module for developers who want to attach files programmatically to emails sent from Drupal 8+. This module doesn't send emails but rather intercepts emails from other modules.

If an 'attachment' or an 'attachments' key is present in the $params array, it will be converted into an actual MIME attachment. Otherwise, this module doesn't touch the mail.

This module has no configuration options.

Requirements

This module requires Drupal core ^10.1, ^11, or ^12. No additional PHP extensions or contributed modules are needed.

This module hooks into Drupal core's default MailManager via hook_mail_alter(). This module is not compatible with Symfony Mailer, Mailer Plus, DSM+.

Installation

Install the module as you would normally install a contributed Drupal module.

Single attachment

Example code to put into your module:

      $params = [
        'attachment' => [
          'filecontent' =>
            'Your attachment contents. ' .
            'You could use file_get_contents() instead of ' .
            'this string.',
          'filename' => 'filename_how_' .
            'recipients_see_it.txt',
          'filemime' => 'text/plain',
        ],
        // further params as needed by your hook_mail
      ];
      $mail_manager = \Drupal::service('plugin.manager.mail');
      $result = $mail_manager->mail($your_module, $your_key, $to, $lang, $params);

Multiple attachments

If you need to attach more than one file, use the array key 'attachments' instead, and nest your files in an array:

      $params = [
        'attachments' => [
          [
            'filecontent' =>
              'Your attachment contents. ' .
              'You could use file_get_contents() instead of this string.',
            'filename' => 'attached_filename_how_recipients_see_it.txt',
            'filemime' => 'text/plain',
          ],
          [
            'filecontent' => file_get_contents('temporary://test.pdf'),
            'filename' => 'Invoice.pdf',
            'filemime' => 'application/pdf',
          ],
        ],
        // further params as needed by your hook_mail
      ];
      $mail_manager = \Drupal::service('plugin.manager.mail');
      $result = $mail_manager->mail($your_module, $your_key, $to, $lang, $params);

Files can be binary, too.

The 'filemime' key is optional. If it is missing then Drupal's ExtensionMimeTypeGuesser will be used.

The 'filecontent' key is optional, if 'filename' points to an existing file on the webserver.

Inline attachments (embedding images in the HTML body)

To reference an attachment from within the HTML message body itself, for example to embed a QR code or logo as <img src="cid:..."> instead of (or in addition to) offering it as a downloadable attachment, add a 'cid' key and set 'disposition' to 'inline':

      $cid = 'qr-code@example.com';
      $params = [
        'attachment' => [
          'filecontent' => MymoduleElement::getFileString($submission),
          'filename' => 'qr-code.png',
          'filemime' => 'image/png',
          'disposition' => 'inline',
          'cid' => $cid,
        ],
        // further params as needed by your hook_mail
      ];

Then reference the same $cid in the HTML body, without angle brackets:

      $body = '<img alt="QR code" src="cid:' . $cid . '">';

The 'disposition' key is optional and defaults to 'attachment'. The 'cid' key is optional; without it, no Content-ID header is added and the attachment can't be referenced from the body.

Using hook_mail_alter()

You can also use the mail_alter hook to insert attachments. The following example is for a hypothetical module called “mymodule”:

// attach a file to submission emails sent by the webform module
function mymodule_mail_alter(array &$message): void {
  if (isset($message['module']) && $message['module'] == 'webform') {
      $message['params']['attachments'][] = [
        'filecontent' => MymoduleElement::getFileString($message['params']['webform_submission']),
        'filename' => t('QR code') . '.png',
        'filemime' => 'image/png',
      ];
  }
}

Examples

For working examples, see the email_attachment_demo sub-module and the webform_qr_code_element contrib module.

Maintainer

Christian “Gogowitsch” Bläul.

Support

To submit bug reports and feature suggestions, or to track changes, use the issue queue.

To say “thank you” or financially support development of this module, you can send a few Euros via PayPal: paypal@blaeul.de or various other means.