Email Class
***********

CodeIgniter’s robust Email Class supports the following features:

* Multiple Protocols: Mail, Sendmail, and SMTP

* TLS and SSL Encryption for SMTP

* Multiple recipients

* CC and BCCs

* HTML or Plaintext email

* Attachments

* Word wrapping

* Priorities

* BCC Batch Mode, enabling large email lists to be broken into small
  BCC batches.

* Email Debugging tools

* Using the Email Library

  * Sending Email

  * Setting Email Preferences

    * Setting Email Preferences in a Config File

  * Email Preferences

  * Overriding Word Wrapping

* Class Reference


Using the Email Library
=======================


Sending Email
-------------

Sending email is not only simple, but you can configure it on the fly
or set your preferences in a config file.

Here is a basic example demonstrating how you might send email. Note:
This example assumes you are sending the email from one of your
controllers.

   $this->load->library('email');

   $this->email->from('your@example.com', 'Your Name');
   $this->email->to('someone@example.com');
   $this->email->cc('another@another-example.com');
   $this->email->bcc('them@their-example.com');

   $this->email->subject('Email Test');
   $this->email->message('Testing the email class.');

   $this->email->send();


Setting Email Preferences
-------------------------

There are 21 different preferences available to tailor how your email
messages are sent. You can either set them manually as described here,
or automatically via preferences stored in your config file, described
below:

Preferences are set by passing an array of preference values to the
email initialize method. Here is an example of how you might set some
preferences:

   $config['protocol'] = 'sendmail';
   $config['mailpath'] = '/usr/sbin/sendmail';
   $config['charset'] = 'iso-8859-1';
   $config['wordwrap'] = TRUE;

   $this->email->initialize($config);

Note:

  Most of the preferences have default values that will be used if you
  do not set them.


Setting Email Preferences in a Config File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you prefer not to set preferences using the above method, you can
instead put them into a config file. Simply create a new file called
the email.php, add the $config array in that file. Then save the file
at config/email.php and it will be used automatically. You will NOT
need to use the "$this->email->initialize()" method if you save your
preferences in a config file.


Email Preferences
-----------------

The following is a list of all the preferences that can be set when
sending email.

+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| Preference          | Default Value          | Options                      | Description                                                             |
|=====================|========================|==============================|=========================================================================|
| **useragent**       | CodeIgniter            | None                         | The “user agent”.                                                       |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **protocol**        | mail                   | mail, sendmail, or smtp      | The mail sending protocol.                                              |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **mailpath**        | /usr/sbin/sendmail     | None                         | The server path to Sendmail.                                            |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_host**       | No Default             | None                         | SMTP Server Address.                                                    |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_user**       | No Default             | None                         | SMTP Username.                                                          |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_pass**       | No Default             | None                         | SMTP Password.                                                          |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_port**       | 25                     | None                         | SMTP Port.                                                              |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_timeout**    | 5                      | None                         | SMTP Timeout (in seconds).                                              |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_keepalive**  | FALSE                  | TRUE or FALSE (boolean)      | Enable persistent SMTP connections.                                     |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **smtp_crypto**     | No Default             | tls or ssl                   | SMTP Encryption                                                         |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **wordwrap**        | TRUE                   | TRUE or FALSE (boolean)      | Enable word-wrap.                                                       |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **wrapchars**       | 76                     |                              | Character count to wrap at.                                             |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **mailtype**        | text                   | text or html                 | Type of mail. If you send HTML email you must send it as a complete web |
|                     |                        |                              | page. Make sure you don’t have any relative links or relative image     |
|                     |                        |                              | paths otherwise they will not work.                                     |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **charset**         | "$config['charset']"   |                              | Character set (utf-8, iso-8859-1, etc.).                                |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **validate**        | FALSE                  | TRUE or FALSE (boolean)      | Whether to validate the email address.                                  |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **priority**        | 3                      | 1, 2, 3, 4, 5                | Email Priority. 1 = highest. 5 = lowest. 3 = normal.                    |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **crlf**            | \n                     | “\r\n” or “\n” or “\r”       | Newline character. (Use “\r\n” to comply with RFC 822).                 |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **newline**         | \n                     | “\r\n” or “\n” or “\r”       | Newline character. (Use “\r\n” to comply with RFC 822).                 |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **bcc_batch_mode**  | FALSE                  | TRUE or FALSE (boolean)      | Enable BCC Batch Mode.                                                  |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **bcc_batch_size**  | 200                    | None                         | Number of emails in each BCC batch.                                     |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+
| **dsn**             | FALSE                  | TRUE or FALSE (boolean)      | Enable notify message from server                                       |
+---------------------+------------------------+------------------------------+-------------------------------------------------------------------------+


Overriding Word Wrapping
------------------------

If you have word wrapping enabled (recommended to comply with RFC 822)
and you have a very long link in your email it can get wrapped too,
causing it to become un-clickable by the person receiving it.
CodeIgniter lets you manually override word wrapping within part of
your message like this:

   The text of your email that
   gets wrapped normally.

   {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

   More text that will be
   wrapped normally.

Place the item you do not want word-wrapped between: {unwrap}
{/unwrap}


Class Reference
===============

class CI_Email

   from($from[, $name = ''[, $return_path = NULL]])

      Parameters:
         * **$from** ("string") – “From” e-mail address

         * **$name** ("string") – “From” display name

         * **$return_path** ("string") – Optional email address to
           redirect undelivered e-mail to

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the email address and name of the person sending the email:

         $this->email->from('you@example.com', 'Your Name');

      You can also set a Return-Path, to help redirect undelivered
      mail:

         $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');

      Note:

        Return-Path can’t be used if you’ve configured ‘smtp’ as your
        protocol.

   reply_to($replyto[, $name = ''])

      Parameters:
         * **$replyto** ("string") – E-mail address for replies

         * **$name** ("string") – Display name for the reply-to e-mail
           address

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the reply-to address. If the information is not provided
      the information in the :meth:from method is used. Example:

         $this->email->reply_to('you@example.com', 'Your Name');

   to($to)

      Parameters:
         * **$to** ("mixed") – Comma-delimited string or an array of
           e-mail addresses

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the email address(s) of the recipient(s). Can be a single
      e-mail, a comma-delimited list or an array:

         $this->email->to('someone@example.com');

         $this->email->to('one@example.com, two@example.com, three@example.com');

         $this->email->to(
                 array('one@example.com', 'two@example.com', 'three@example.com')
         );

   cc($cc)

      Parameters:
         * **$cc** ("mixed") – Comma-delimited string or an array of
           e-mail addresses

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the CC email address(s). Just like the “to”, can be a
      single e-mail, a comma-delimited list or an array.

   bcc($bcc[, $limit = ''])

      Parameters:
         * **$bcc** ("mixed") – Comma-delimited string or an array of
           e-mail addresses

         * **$limit** ("int") – Maximum number of e-mails to send per
           batch

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the BCC email address(s). Just like the "to()" method, can
      be a single e-mail, a comma-delimited list or an array.

      If "$limit" is set, “batch mode” will be enabled, which will
      send the emails to batches, with each batch not exceeding the
      specified "$limit".

   subject($subject)

      Parameters:
         * **$subject** ("string") – E-mail subject line

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the email subject:

         $this->email->subject('This is my subject');

   message($body)

      Parameters:
         * **$body** ("string") – E-mail message body

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the e-mail message body:

         $this->email->message('This is my message');

   set_alt_message($str)

      Parameters:
         * **$str** ("string") – Alternative e-mail message body

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Sets the alternative e-mail message body:

         $this->email->set_alt_message('This is the alternative message');

      This is an optional message string which can be used if you send
      HTML formatted email. It lets you specify an alternative message
      with no HTML formatting which is added to the header string for
      people who do not accept HTML email. If you do not set your own
      message CodeIgniter will extract the message from your HTML
      email and strip the tags.

   set_header($header, $value)

      Parameters:
         * **$header** ("string") – Header name

         * **$value** ("string") – Header value

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Appends additional headers to the e-mail:

         $this->email->set_header('Header1', 'Value1');
         $this->email->set_header('Header2', 'Value2');

   clear([$clear_attachments = FALSE])

      Parameters:
         * **$clear_attachments** ("bool") – Whether or not to clear
           attachments

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Initializes all the email variables to an empty state. This
      method is intended for use if you run the email sending method
      in a loop, permitting the data to be reset between cycles.

         foreach ($list as $name => $address)
         {
                 $this->email->clear();

                 $this->email->to($address);
                 $this->email->from('your@example.com');
                 $this->email->subject('Here is your info '.$name);
                 $this->email->message('Hi '.$name.' Here is the info you requested.');
                 $this->email->send();
         }

      If you set the parameter to TRUE any attachments will be cleared
      as well:

         $this->email->clear(TRUE);

   send([$auto_clear = TRUE])

      Parameters:
         * **$auto_clear** ("bool") – Whether to clear message data
           automatically

      Returns:
         TRUE on success, FALSE on failure

      Return type:
         "bool"

      The e-mail sending method. Returns boolean TRUE or FALSE based
      on success or failure, enabling it to be used conditionally:

         if ( ! $this->email->send())
         {
                 // Generate error
         }

      This method will automatically clear all parameters if the
      request was successful. To stop this behaviour pass FALSE:

         if ($this->email->send(FALSE))
         {
                 // Parameters won't be cleared
         }

      Note:

        In order to use the "print_debugger()" method, you need to
        avoid clearing the email parameters.

   attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])

      Parameters:
         * **$filename** ("string") – File name

         * **$disposition** ("string") – ‘disposition’ of the
           attachment. Most email clients make their own decision
           regardless of the MIME specification used here.
           https://www.iana.org/assignments/cont-disp/cont-disp.xhtml

         * **$newname** ("string") – Custom file name to use in the
           e-mail

         * **$mime** ("string") – MIME type to use (useful for
           buffered data)

      Returns:
         CI_Email instance (method chaining)

      Return type:
         "CI_Email"

      Enables you to send an attachment. Put the file path/name in the
      first parameter. For multiple attachments use the method
      multiple times. For example:

         $this->email->attach('/path/to/photo1.jpg');
         $this->email->attach('/path/to/photo2.jpg');
         $this->email->attach('/path/to/photo3.jpg');

      To use the default disposition (attachment), leave the second
      parameter blank, otherwise use a custom disposition:

         $this->email->attach('image.jpg', 'inline');

      You can also use a URL:

         $this->email->attach('http://example.com/filename.pdf');

      If you’d like to use a custom file name, you can use the third
      parameter:

         $this->email->attach('filename.pdf', 'attachment', 'report.pdf');

      If you need to use a buffer string instead of a real - physical
      - file you can use the first parameter as buffer, the third
      parameter as file name and the fourth parameter as mime-type:

         $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');

   attachment_cid($filename)

      Parameters:
         * **$filename** ("string") – Existing attachment filename

      Returns:
         Attachment Content-ID or FALSE if not found

      Return type:
         "string"

      Sets and returns an attachment’s Content-ID, which enables your
      to embed an inline (picture) attachment into HTML. First
      parameter must be the already attached file name.

         $filename = '/img/photo1.jpg';
         $this->email->attach($filename);
         foreach ($list as $address)
         {
                 $this->email->to($address);
                 $cid = $this->email->attachment_cid($filename);
                 $this->email->message('<img src="cid:'. $cid .'" alt="photo1" />');
                 $this->email->send();
         }

      Note:

        Content-ID for each e-mail must be re-created for it to be
        unique.

   print_debugger([$include = array('headers', 'subject', 'body')])

      Parameters:
         * **$include** ("array") – Which parts of the message to
           print out

      Returns:
         Formatted debug data

      Return type:
         "string"

      Returns a string containing any server messages, the email
      headers, and the email message. Useful for debugging.

      You can optionally specify which parts of the message should be
      printed. Valid options are: **headers**, **subject**, **body**.

      Example:

         // You need to pass FALSE while sending in order for the email data
         // to not be cleared - if that happens, print_debugger() would have
         // nothing to output.
         $this->email->send(FALSE);

         // Will only print the email headers, excluding the message subject and body
         $this->email->print_debugger(array('headers'));

      Note:

        By default, all of the raw data will be printed.
