README.txt 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136
  1. -- SUMMARY --
  2. This is a Mime Mail component module (for use by other modules).
  3. * It permits users to recieve HTML email and can be used by other modules. The mail
  4. functionality accepts an HTML message body, mime-endcodes it and sends it.
  5. * If the HTML has embedded graphics, these graphics are MIME-encoded and included
  6. as a message attachment.
  7. * Adopts your site's style by automatically including your theme's stylesheet files in a
  8. themeable HTML message format
  9. * If the recipient's preference is available and they prefer plaintext, the HTML will be
  10. converted to plain text and sent as-is. Otherwise, the email will be sent in themeable
  11. HTML with a plaintext alternative.
  12. For a full description of the module, visit the project page:
  13. http://drupal.org/project/mimemail
  14. To submit bug reports and feature suggestions, or to track changes:
  15. http://drupal.org/project/issues/mimemail
  16. -- REQUIREMENTS --
  17. Mail System module - http://drupal.org/project/mailsystem
  18. -- INSTALLATION --
  19. Hopefully, you know the drill by now :)
  20. 1. Download the module and extract the files.
  21. 2. Upload the entire mimemail folder into your Drupal sites/all/modules/
  22. or sites/my.site.folder/modules/ directory if you are running a multi-site
  23. installation of Drupal and you want this module to be specific to a
  24. particular site in your installation.
  25. 3. Enable the Mime Mail module by navigating to:
  26. Administration > Modules
  27. 4. Adjust settings by navigating to:
  28. Administration > Configuration > Mime Mail
  29. -- USAGE --
  30. This module may be required by other modules, but in favor of the recently
  31. added system actions and Rules integration, it can be useful by itself too.
  32. Once installed, any module can send MIME-encoded messages by specifing
  33. MimeMailSystem as the responsible mail system for a particular message
  34. or all mail sent by one module.
  35. This can be done through the web by visiting admin/config/system/mailsystem
  36. or in a program as follows:
  37. mailsystem_set(array(
  38. '{$module}_{$key}' => 'MimeMailSystem', // Just messages with $key sent by $module.
  39. '{$module}' => 'MimeMailSystem', // All messages sent by $module.
  40. ));
  41. You can use the following optional parameters to build the e-mail:
  42. 'plain':
  43. Boolean, whether to send messages in plaintext-only (optional, default is FALSE).
  44. 'plaintext':
  45. Plaintext portion of a multipart e-mail (optional).
  46. 'attachments':
  47. Array of arrays with the path or content, name and MIME type of the file (optional).
  48. 'headers':
  49. A keyed array with headers (optional).
  50. You can set these in $params either before calling drupal_mail() or in hook_mail()
  51. and of course hook_mail_alter().
  52. Normally, Mime Mail uses email addresses in the form of "name" <address@host.com>,
  53. but PHP running on Windows servers requires extra SMTP handling to use this format.
  54. If you are running your site on a Windows server and don't have an SMTP solution such
  55. as the SMTP module installed, you may need to set the 'Use the simple format of
  56. user@example.com for all email addresses' option on the configuration settings page.
  57. This module creates a user preference for receiving plaintext-only messages.
  58. This preference will be honored by all messages if the format is not explicitly set
  59. and the user has access to edit this preference (allowed by default).
  60. Email messages are formatted using the mimemail-message.tpl.php template.
  61. This includes a CSS style sheet and uses an HTML version of the text.
  62. The included CSS is either:
  63. the mail.css file found anywhere in your theme folder or
  64. the combined CSS style sheets of your theme if enabled.
  65. Since some email clients (namely Outlook 2007 and GMail) is tend to only regard
  66. inline CSS, you can use the Compressor to convert CSS styles into inline style
  67. attributes. It transmogrifies the HTML source by parsing the CSS and inserting the
  68. CSS definitions into tags within the HTML based on the CSS selectors. To use the
  69. Compressor, just enable it.
  70. To create a custom mail template copy the mimemail-message.tpl.php file from
  71. the mimemail/theme directory into your default theme's folder. Both general and
  72. by-mailkey theming can be performed:
  73. mimemail-message--[module]--[key].tpl.php (for messages with a specific module and key)
  74. mimemail-message--[module].tpl.php (for messages with a specific module)
  75. mimemail-message--[key].tpl.php (for messages with a specific key)
  76. mimemail-message.tpl.php (for all messages)
  77. Messages can be rendered using different themes. You can choose the following
  78. settings to render the e-mail:
  79. 'current': Theme currently used by the user who runs drupal_mail().
  80. 'default': Default theme, obtained via variable theme_default.
  81. 'domain': Theme obtained via Domain Theme module.
  82. or any other active theme.
  83. Images with absolute URL will be available as remote content. To embed images
  84. into emails you have to use a relative URL or an internal path. Due to security
  85. concerns, only files residing in the public file system (e.g sites/default/files)
  86. can be used by default.
  87. For example:
  88. instead of http://www.mysite.com/sites/default/files/mypicture.jpg
  89. use /home/www/public_html/drupal/sites/default/files/mypicture.jpg
  90. or /sites/default/files/mypicture.jpg
  91. or public://mypicture.jpg
  92. The 'send arbitrary files' permission allows you to attach or embed files located
  93. outside Drupal's public files directory. Note that this has security implications:
  94. arbitrary means even your settings.php! Give to trusted roles only!
  95. -- CREDITS --
  96. MAINTAINER: Allie Micka < allie at pajunas dot com >
  97. * Allie Micka
  98. Mime enhancements and HTML mail code
  99. * Gerhard Killesreiter
  100. Original mail and mime code
  101. * Robert Castelo
  102. HTML to Text and other functionality