Attachments, Inline Images and Advanced Usage

This page is targeted towards developers. It demonstrates how the message format of any given e-mail can be set, along with how files and inline images can be attached to e-mails.

Attachments

You can easily add attachments to e-mails. This can be done programatically by defining one or more files to attach.

All files which are to be attached to an e-mail need to be represented as instances of stdClass. This makes it easy for you to add files that are managed by Drupal, as the file_load() function will return an stdClass instance which represents a given file.

All stdClass instances returned by Drupal which represents files are populated with the fields 'uri', 'filename' and 'filemime'. Thus, if you would like to attach a file that are not managed by drupal, you then need to create an instance of stdClass and populate that instance with the fields 'uri', 'filename' and 'filemime'. Drupal's drupal_realpath() will be used to determine the actual location of the provided file as given in the 'uri' field. Thus, files from both public and private file systems can be attached to e-mails.

Note! The Swift Mailer module has not been tested with stream wrappers other than the default public and private. It might not work other stream wrappers.

The below example demonstrates both how to attach a file managed by Drupal and a file which is not managed by Drupal.

Note! You can specify which files to add as attachments both from the code block where you invoke drupal_mail() and from your module's implementation of hook_mail(). In hook_mail(), simply make sure you add attachments to $message['params']['files'] and not to the provided $params argument.

/**
 * Send an e-mail.
 */
function test() {

  //File one (managed by Drupal).
  $file_one = file_load(1);

  //File two (not managed by Drupal).
  $file_two = new stdClass();
  $file_two->uri = 'sites/default/files/images/drupal_logo.jpg';
  $file_two->filename = 'drupal_logo.jpg';
  $file_two->filemime = 'image/jpeg';
  
  // Add attachments.
  $p['files'][] = $file_one;
  $p['files'][] = $file_two;

  // Send e-mail.
  drupal_mail('modulename', 'key', 'test@test.com', language_default(), $p);
}

/**
 * Implementation of hook_mail().
 */
function modulename_mail($key, &$message, $params) {

  switch($key) {
    default:
      $text[] = t('<strong>Hi</strong>');
      $text[] = t('<p>This is an automatically generated test e-mail.</p>');

      //File three (managed by Drupal).
      $file_three = file_load(2);
      $message['params']['files'][] = $file_three;

      $message['subject'] = t('Test');
      $message['body'] = $text;
      break;
    }

}

It should be stressed that the module only supports attaching already existing files. In other words, dynamically generated files which are to be added as attachment to an e-mail needs to be generated and stored in a permanent or temporary location before it is provided as an attachment. A recommended way to handle temporary files is to utilise Drupals file system and mark the files as temporary. Drupal will then take care of deleting those files after a set amount of time.

The Attachment Hook

The SwiftMailer module allows other modules to add attachments to e-mails. This is done through hook_swiftmailer_attach() which other modules need to implement in order to add attachments to e-mails. The below block of code demonstrates how a module can add attachments to an e-mail using hook_swiftmailer_attach().

function swiftmailer_swiftmailer_attach($key) {

    // Load file which is managed by Drupal.
    return file_load(2);

}

Inline Images

Adding inline images to e-mails is just as easy as adding files as attachments. You can choose between two ways of adding images. The first one assumes that your module does all the work, and the second assumes that your theme takes care of specifying which images to display as inline images.

Let your module do the work!

Images which are to be attached to an e-mail need to be represented as instances of stdClass. This makes it easy for you to add image files that are managed by Drupal, as the file_load() function will return an stdClass instance which represents a given image file. However, in contrast to attachments, you will need to manually apply the field 'cid' to an image file which is to be used as an inline image. The 'cid' field needs to hold the id of the image file, and will be used to establish a link between the attached image and its display location in the e-mail body.

All stdClass instances returned by Drupal which represents (image) files are populated with the fields 'uri', 'filename' and 'filemime'. Thus, if you would like to attach an image file that are not managed by Drupal, you then need to create an instance of stdClass and populate that instance with the fields 'uri', 'filename' and 'filemime'. Drupal's drupal_realpath() will be used to determine the actual location of the provided image file as given in the 'uri' field. Thus, image files from both public and private file systems can be attached to e-mails.

The below example demonstrates both how to attach an image file that is managed by Drupal.

/**
 * Implementation of hook_mail().
 */
function modulename_mail($key, &$message, $params) {

  switch($key) {
    default:
      
      $logo_id = '390ffcm-sdfd94f';
    
      $text[] = '<img src="cid:' . $logo_id . '" />;
      $text[] = t('<p>This is an automatically generated test e-mail with an
                   inline image..</p>');

      //Inline image (managed by Drupal).
      $inline_image = file_load(1);
      $inline_image->cid = $logo_id;
      $message['images'][] = $inline_image;

      $message['subject'] = t('Test');
      $message['body'] = $text;
      break;
    }

}

Let your theme do the work!

Adding inline images from a theme might be even easier than adding inline images from a module. The first thing you need to do is to add markup to your the theme file which is responsible for showing the images. Now, the markup needs to be a little different than the markup required when adding inline images from a module. Instead of referencing images by CID, you simply reference images by their path. The below line of code demonstrates this.

<img src="image:/sites/all/themes/mytheme/images/logo.jpg">
<img src="image:<?php print drupal_get_path('module', 'mymodule') .
'/images/drupal.jpg'; ?>" />

The essential part in the above lines of code is to make sure that the path of the image is prefixed with 'image:'. This tells the Swift Mailer module to embed that image file. The Swift Mailer module will automatically take care of assigning the image a CID to establish a link between the image and the markup.

Message Format

You can specify wether a message should be sent as plain text ('text/plain') or HTML ('text/html'). Furthermore, the character set can also be set. The below example demonstrates how this can be achieved.

/**
 * Send an e-mail
 *
 */
function test() {
  
  // Define message format. 
  $p = array(
    'format' => 'text/html', 
    'charset' => 'UTF-8',
    );
   
  // Send message.
  drupal_mail('mymodule', 'key', 'test@test.com', language_default(), $p);
  
}

The above example will send an e-mail message as plain text.