^Status|Draft|
^Todo|fuller description of driver (when to use one over another). Test attachment example fully|

====== Email Helper ======

An Email helper to work with the Swift email library. You **need to** have the Swiftmailer library in the vendor directory if you want the helper to work. The directory structure must be:

  vendor
   +- swift
   |    +- Swift
   |        |  ...
   |        |  ...
   |    -- Swift.php
   |    -- EasySwift.php

  * You can choose to download Swiftmailer along with your Kohana archive in the [[http://kohanaphp.com/download|download page]]
  * Or you can manually [[http://www.swiftmailer.org/download/|download]] and extract it in the vendor directory.

===== Configuration =====

The swiftmailer configuration is done in the application/config/email.php file, if it's not there take the one from system/config and copy it to the application folder (see [[http://docs.kohanaphp.com/general/filesystem|cascading filesystem]]): 

<code php>
// Valid drivers are: native, sendmail, smtp
$config['driver'] = 'native';

// Driver options:
$config['options'] = NULL;
</code>

=== Drivers  ===

''config['driver']'' sets the SwiftMailer driver. Valid drivers are: 

  * native
  * sendmail
  * smtp

=== Drivers options ===

$config['options'] contains driver specific parameters.

  * smtp: hostname, port, username, password, encryption
    * //Note: Do **not** use the "auth" parameter if you're providing a name and password with smtp as it will cause a runtime error -- the auth parameter is only for special authentication methods like POPb4SMTP (see [[http://forum.kohanaphp.com/comments.php?DiscussionID=1881]] for more details).//


<code php>
// Standard smtp connection
$config['options'] = array('hostname'=>'yourhostname', 'port'=>'25', 'username'=>'yourusername', 'password'=>'yourpassword');

// Secure SMTP connections
$config['options'] =  array('hostname'=>'smtp.gmail.com', 'port'=>'465', 'username'=>'yourusername', 'password'=>'yourpassword', 'encryption' => 'tls');
</code>

  * sendmail: executable path or leave empty if you want Swift to auto detect sendmail path.

<code php>
$config['options'] = '/path/to/sendmail';
</code>

===== Usage examples =====

==== Sending a basic email ====

To send a basic HTML email, use the code below:

<code php>
$to      = 'to@example.com';  // Address can also be array('to@example.com', 'Name')
$from    = 'from@example.com';
$subject = 'This is an example subject';
$message = 'This is an <strong>example</strong> message';

email::send($to, $from, $subject, $message, TRUE);
</code>

==== Sending advanced emails ====

To send advanced emails you need to use [[http://www.swiftmailer.org/wikidocs/|Swift mailer methods]]. The code below show how to send an email with an attachment and multiple recipients. For advanced emails, Swiftmailer methods and classes will be directly used. ''email::connect'' can still be used to load Swiftmailer library and set the appropriate settings made in the config file config/email.php.

This example will not work correctly anymore due to a Swift Mailer bug.

<code php>
// Use connect() method to load Swiftmailer and connect using the parameters set in the email config file 
$swift = email::connect(); 

// From, subject and HTML message
$from = 'from@example.com';
$subject = 'Backup: ' . date("d/m/Y");
$message = 'This is the <b>backup</b> for ' . date("d/m/Y");

// Build recipient lists
$recipients = new Swift_RecipientList;
$recipients->addTo('to1@example.com');
$recipients->addTo('to2@example.com');

// Build the HTML message 
$message = new Swift_Message($subject, $message, "text/html");

// Attachment
$swiftfile = new Swift_File('/backups/dump-' . date("d-m-Y") . '.tar.gz'); 
$attachment = new Swift_Message_Attachment($swiftfile);
$message->attach($attachment);

if ($swift->send($message, $recipients, $from))
{ 
  // Success
}
else
{
  // Failure
} 

// Disconnect
$swift->disconnect();
</code>

===== Methods =====

==== connect() ====

'connect' creates a SwiftMailer instance according to the driver and parameters set in the config file. 

==== send() ====

'send' sends an e-mail using the specified information. 
The parameters are:
  * [string|array] recipient email (and name), or an array of To, Cc, Bcc names
  * [string|array] sender email (and name)
  * [string] message subject
  * [string] message body
  * [boolean] send email as HTML (defaults to false)
  * return [integer] number of emails sent