API change: Split mail preparation from sending

With this patch we can use mimemail() for sending or only for preparing like drupal_mail() - see http://api.drupal.org/api/drupal/includes--mail.inc/function/drupal_mail/6.

A new argument $send was appended and 2 wrapper functions were added: mimemail_prepare() & mimemail_send().

Wanna prepare the message but not send it? For example we want to spool and not send it.

$message = mimemail_prepare($sender, $recipient, $subject, $body, $plaintext, $headers, $text, $attachments, $mailkey);

or

$message = mimemail($sender, $recipient, $subject, $body, $plaintext, $headers, $text, $attachments, $mailkey, FALSE);

Wanna send an already prepared message? Example: Send prepared messages from a spool queue

mimemail_send($message);

Also reordered functions inside module because they were somehow mixed.

@sgabe,

You can't add a new function named mimemail_prepare() because Drupal core has a hook_prepare().

Good catch! But a "send" wrapper must be added as drupal_mail_send() is for drupal_mail(). If we don't have the second function we cannot send directly a "prepared" messages.

I've integrated Mimemail in Views Send module. Messages are spooled and the module philosophy is to alter/prepare/render everything when adding messages to the queue. On cron the queue is processed and I need only the send part which needs a API function.

Should we leave it as mimemail_send() or rename it as mimemail_mail_send() (for similarity reasons)?

Here's a patch based on #3 and #4.

Switched to classical patch format as is easiest to read and don't want my e-mail listed.

Note that now mimemail() really returns the whole $message array as it was already state (but not effective) in phpdoc:

 * @return
 *   An array containing the MIME encoded message, including headers and body.

This is an API change and modules using mimemail()must adapt.

Added also the README.txt and deleted a trailing space somewhere in the last patch.

Created a patch for Webform 6.x-3.x-dev here http://drupal.org/node/1087598. I'm not using Simplenews so I cannot test/patch.