=========================
 How to use the MIME API
=========================

.. contents:: Contents
.. section-numbering::

------------------------
 Creating MIME messages
------------------------

Scenario: We have a text block (such as text/calendar data) which needs to be added as a MIME part to an email message. We then need to add a couple of additional headers to this message and finally read it back as a string.

For Message Body:
::

 require_once 'Horde/MIME/Message.php';
 $message = new MIME_Message();
 $part = new MIME_Part('text/plain', $message_text);
 $message->addPart($part);

For text/calendar attachment:
::

 $part = new MIME_Part('text/calendar', $text_calendar_data);
 $message->addPart($part);

For Headers:
::

 require_once 'Horde/MIME/Headers.php';
 $headers = new MIME_Headers();
 $headers->addHeader('Header 1', $Header_1_Value);
 $headers->addHeader('Header 2', $Header_2_Value);
 $headers->addMIMEHeaders($message);

To return the message as a string:
::

 $string = $headers->toString() . "\n\n" . $message->toString();

-----------------------------------------------------------------------------
 Creating and Sending E-Mail with an attachment by using the MIME_Mail class
-----------------------------------------------------------------------------

::

 require_once 'Horde/MIME/Mail.php';
 
 // New Horde MIME_Mail Object
 $mail = new MIME_Mail();
 
 // Set the header date
 $mail->addHeader('Date', date('r'));
 
 // Set the from address
 $mail->addHeader('From', 'sender@example.com');
 
 // Set the subject of the mail
 $mail->addHeader('Subject', 'Horde MIME_Mail example');
 
 // Set the text message body
 $mail->setBody('Example MIME message with an attachment');
 
 // Add the file as an attachment, set the file name and what kind of file it is.
 $mail->addAttachment('/tmp/some_file.zip', 'some_file.zip', 'application/x-zip-compressed');
 
 // Add recipients
 $mail->addRecipients('recipient@example.com');
 
 // Get the mail driver
 $mail_driver = $conf['mailer']['type'];
 $mail_params = $conf['mailer']['params'];
 if ($mail_driver == 'smtp' && $mail_params['auth'] &&
     empty($mail_params['username'])) {
     if (Auth::getAuth()) {
         $mail_params['username'] = Auth::getAuth();
         $mail_params['password'] = Auth::getCredential('password');
     }
 }
 
 // Send the mail
 if (!is_a($sent = $mail->send($mail_driver, $mail_params), 'PEAR_Error')) {
     print "E-Mail sent\n";
 } else {
     print "E-Mail not sent\n";
 }

------------------------
 Parsing a MIME message
------------------------

Scenario: We have an existing text string which contains a valid MIME email message.  We need to parse this string in order to read back the body of a specific MIME part with a certain content type.

::

 require_once 'Horde/MIME/Structure.php';
 $message = MIME_Structure::parseTextMIMEMessage($message_text);

If you have access to the mail server, you can also use:

::

 $structure = @imap_fetchstructure($stream, $uid, FT_UID);
 $message = MIME_Structure::parse($structure);

To determine the structure of the MIME message, e.g. to find out the MIME ID we are looking for:

::

 $map = $message->contentTypeMap();

$map is an array with key being the MIME IDs and values being the Content Types of that IDs.

To retrieve a certain MIME part of the message:

::

 $part = $message->getPart($mime_id);

The following code snippets require at least Horde 3.2.

To retrieve the body text:

::

 require_once 'Horde/MIME/Contents.php';
 $contents = new MIME_Contents($message);
 $body_id = $contents->findBody();
 if ($body_id) {
     $part = &$contents->getMIMEPart($body_id);
     $body = $part->transferDecode();
 } else {
     $body = 'Could not render body of message.';
 }

To retrieve the HTML body text if any exists:

::

 require_once 'Horde/MIME/Contents.php';
 $contents = new MIME_Contents($message);
 $body_id = $contents->findBody('html');
 if (is_null($body_id)) {
     $body_id = $contents->findBody();
 }
 if ($body_id) {
     $part = &$contents->getMIMEPart($body_id);
     $body = $part->transferDecode();
 } else {
     $body = 'Could not render body of message.';
 }

To retrieve a list of all attachments:

::

 $attachments = $contents->getAttachmentContents();
 foreach ($attachments as $attachment) {
     echo 'Attachment ' . htmlspecialchars($attachment['name']) . ' is ' . strlen($attachment['data']) . ' bytes long.';
 }

If you don't retrieve all attachments as expected, in particular if any attached mail/rfc822 parts are returned empty, apply the patch mimeDecode.php.patch that has been attached to this wiki page to the file Mail/mimeDecode.php in your PEAR directory.

--------------------
 Using MIME Viewers
--------------------

Scenario: Continuing the previous example we want to render the text/calendar part to HTML. *This code currently only works inside of a Horde application because it relies on the registry and Horde's configuration files.*

::

 require HORDE_BASE . '/config/mime_drivers.php';
 require_once 'Horde/MIME/Viewer.php';
 $viewer = MIME_Viewer::factory($part);
 $html = $viewer->render();

-------------------------
 Reading message headers
-------------------------

Using a mail server connection
==============================

Scenario: We want to read a certain message from a certain message on the mail server, for example to search for messages with a known header.

::

 /* Load libraries. */
 require_once 'Horde/MIME/Headers.php';
 require_once 'Horde/NLS.php';
 
 /* Custom MIME_Headers class because we need to implement _getStream(). */
 class MyHeaders extends MIME_Headers {
 
     function _getStream()
     {
         return imap_open('{localhost/imap}INBOX', 'username', 'password');
     }
 }
 
 /* Get message subject. */
 $headers = new MyHeaders($message_uid);
 $headers->buildHeaders();
 $subject = $headers->getValue('Subject');

Using a header text
===================

If the headers can't be received from an IMAP server or already are available as a string, this alternative approach could be used:

::

 $headerText = 'Return-Path: <john@example.com>
 Message-ID: <20080228160832.604925ntqxdo4o00@example.com>
 Date: Thu, 28 Feb 2008 16:08:32 +0100
 From: John Doe <john@example.com>
 To: jane@example.com
 Subject: Some Subject';
 
 /* Load libraries. */
 require_once 'Horde/MIME/Structure.php';
 
 /* Get message subject. */
 $headers = MIME_Structure::parseMIMEHeaders($headerText);
 $subject = $headers['Subject'];

-------------------------
 Complete example script
-------------------------

This is a complete example script that parses all messages of an INBOX for any CSV attachments, extract these attachments from the messages, saves them in a folder, and deletes the parsed message. The script can also be downloaded from the `AttachedFiles`_ area of this page.

.. _`AttachedFiles`: https://wiki.horde.org/AttachedFiles?referrer=Doc%2FDev%2FMimeH3

::

 #!/usr/bin/php
 <?php
 
 /* IMAP/POP3 server settings. */
 $imap_user = '';
 $imap_pass = '';
 $imap_host = 'localhost';
 $imap_protocol = 'imap/notls';
 
 /* Directory where the CSV attachments get stored WITH trailing slash. */
 $target_dir = '/home/jan/csv/';
 
 /* Search string for potential messages.
  * Might be optimized by using something like 'SUBJECT "Always the same"'. */
 $imap_search = 'ALL';
 
 /* Possible mime types of CSV attachments. */
 $csv_mimetypes = array('text/plain',
                        'text/x-comma-separated-values',
                        'application/csv',
                        'application/vnd.ms-excel');
 
 /* If necessary set the include path to the location where PEAR and the Horde
  * packages are installed. */
 // ini_set('include_path', '/usr/share/php');
 
 /****************************************************************************/
 
 /**
  * Shows all IMAP errors and exits.
  */
 function error_out()
 {
     $errors = imap_errors();
     if ($errors) {
         foreach ($errors as $error) {
             echo $error . "\n";
         }
     }
     exit;
 }
 
 /* Load libraries. */
 require_once 'Horde/CLI.php';
 require_once 'Horde/MIME/Structure.php';
 require_once 'Horde/MIME/Headers.php';
 require_once 'Horde/NLS.php';
 
 /* Setup CLI. */
 if (!Horde_CLI::runningFromCLI()) {
     exit("Must be run from the command line\n");
 }
 Horde_CLI::init();
 
 /* Custom MIME_Headers class. */
 class MyHeaders extends MIME_Headers {
 
     function _getStream()
     {
         return $GLOBALS['imap'];
     }
 }
 
 /* Open IMAP connection. */
 $imap = imap_open(sprintf('{%s/%s}INBOX', $imap_host, $imap_protocol),
                   $imap_user, $imap_pass);
 if (!$imap) {
     error_out();
 }
 
 /* Regexp for target filename. */
 $regexp = '/_(\d+).csv$/';
 
 /* Get all messages from the folder. */
 $messages = imap_search($imap, $imap_search, FT_UID);
 
 foreach ($messages as $uid) {
     $struct = imap_fetchstructure($imap, $uid, FT_UID);
 
     /* Is this no multipart message? */
     if ($struct->type != 1) {
         continue;
     }
 
     /* Parse message structure. */
     $body = imap_fetchheader($imap, $uid, FT_UID) .
             imap_body($imap, $uid, FT_UID);
     $message = MIME_Structure::parseTextMIMEMessage($body);
     $map = $message->contentTypeMap();
 
     /* Search for message with possible CSV attachment. */
     foreach ($map as $mime_id => $mime_type) {
         if (!in_array($mime_type, $csv_mimetypes)) {
             continue;
         }
         $mime_part = $message->getPart($mime_id);
         $filename = $mime_part->getName(true);
         if (String::lower(substr($filename, -4)) != '.csv') {
             continue;
         }
 
         /* CSV file found. */
         $content = $mime_part->transferDecode();
 
         /* Get message subject. */
         $headers = new MyHeaders($uid);
         $headers->buildHeaders();
         $subject = $headers->getValue('Subject');
         if (empty($subject)) {
             $subject = $filename;
         } else {
             $subject .= '.csv';
         }
 
         /* Find unique file name. */
         $filename = preg_replace('/[^a-z0-9_\-\.]/i', '_', $subject);
         while (file_exists($target_dir . $filename)) {
             if (preg_match($regexp, $filename, $match)) {
                 $filename = preg_replace($regexp, '_' . ($match[1] + 1) . '.csv', $filename);
             } else {
                 $filename = substr($filename, 0, -4) . '_1.csv';
             }
         }
         
         /* Write CSV file. */
         $fp = fopen($target_dir . $filename, 'w');
         if (!$fp) {
             exit("Can't open file '" . $target_dir . $filename . "' for writing.\n");
         }
         fwrite($fp, $content);
         fclose($fp);
 
         /* Delete message. */
         imap_delete($imap, $uid, FT_UID);
     }
 }
 
 /* Purge and close mailbox. */
 // imap_expunge($imap);
 imap_close($imap);
 error_out();