summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/email.rst
diff options
context:
space:
mode:
authorTimothy Warren <tim@timshomepage.net>2011-10-06 03:47:59 +0200
committerTimothy Warren <tim@timshomepage.net>2011-10-06 03:47:59 +0200
commitfb7ff742949e0474dfba30be45be513b3b4f63cc (patch)
tree87b150fd502d0789f9660ca4dc2ace44817813c3 /user_guide_src/source/libraries/email.rst
parentf7a8d86dbc6805a4e52964bbea76738df75b5f35 (diff)
parentec8abee24f456b09ab9d53e88853fe6bd0f7879a (diff)
Merge branch 'develop' of git://github.com/EllisLab/CodeIgniter into develop
Diffstat (limited to 'user_guide_src/source/libraries/email.rst')
-rw-r--r--user_guide_src/source/libraries/email.rst311
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}