Merge branch 'develop' of git://github.com/EllisLab/CodeIgniter into develop

1 files changed, 311 insertions, 0 deletions

diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst
new file mode 100644
index 000000000..6dd546356
--- /dev/null
+++ b/user_guide_src/source/libraries/email.rst
@@ -0,0 +1,311 @@
+###########
+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
+
+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
+:doc:`controllers <../general/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();
+
+	echo $this->email->print_debugger();
+
+Setting Email Preferences
+=========================
+
+There are 17 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 function. 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() function 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_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**
+utf-8
+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.
+Email Function Reference
+========================
+
+$this->email->from()
+--------------------
+
+Sets the email address and name of the person sending the email::
+
+	$this->email->from('you@example.com', 'Your Name');
+
+$this->email->reply_to()
+-------------------------
+
+Sets the reply-to address. If the information is not provided the
+information in the "from" function is used. Example::
+
+	$this->email->reply_to('you@example.com', 'Your Name');
+
+$this->email->to()
+------------------
+
+Sets the email address(s) of the recipient(s). Can be a single email, 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');
+
+::
+
+	$list = array('one@example.com', 'two@example.com', 'three@example.com');
+
+	$this->email->to($list);
+
+$this->email->cc()
+------------------
+
+Sets the CC email address(s). Just like the "to", can be a single email,
+a comma-delimited list or an array.
+
+$this->email->bcc()
+-------------------
+
+Sets the BCC email address(s). Just like the "to", can be a single
+email, a comma-delimited list or an array.
+
+$this->email->subject()
+-----------------------
+
+Sets the email subject::
+
+	$this->email->subject('This is my subject');
+
+$this->email->message()
+-----------------------
+
+Sets the email message body::
+
+	$this->email->message('This is my message');
+
+$this->email->set_alt_message()
+---------------------------------
+
+Sets the alternative email 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.
+
+$this->email->clear()
+---------------------
+
+Initializes all the email variables to an empty state. This function is
+intended for use if you run the email sending function 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);
+
+$this->email->send()
+--------------------
+
+The Email sending function. Returns boolean TRUE or FALSE based on
+success or failure, enabling it to be used conditionally::
+
+	if ( ! $this->email->send())
+	{
+	    // Generate error
+	}
+
+$this->email->attach()
+----------------------
+
+Enables you to send an attachment. Put the file path/name in the first
+parameter. Note: Use a file path, not a URL. For multiple attachments
+use the function 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');
+
+	$this->email->send();
+
+$this->email->print_debugger()
+-------------------------------
+
+Returns a string containing any server messages, the email headers, and
+the email messsage. Useful for debugging.
+
+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}