From 8ede1a2ecbb62577afd32996956c5feaf7ddf9b6 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 13:34:52 -0500 Subject: replacing the old HTML user guide with a Sphinx-managed user guide --- user_guide_src/source/libraries/email.rst | 269 ++++++++++++++++++++++++++++++ 1 file changed, 269 insertions(+) create mode 100644 user_guide_src/source/libraries/email.rst (limited to 'user_guide_src/source/libraries/email.rst') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst new file mode 100644 index 000000000..025d04b11 --- /dev/null +++ b/user_guide_src/source/libraries/email.rst @@ -0,0 +1,269 @@ +########### +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} -- cgit v1.2.3-24-g4f1b From 3c356847d0ef5cdedf35105a9dc4295d97185ce8 Mon Sep 17 00:00:00 2001 From: Derek Jones Date: Wed, 5 Oct 2011 16:14:23 -0500 Subject: fixed code block spacing in Email lib docs --- user_guide_src/source/libraries/email.rst | 56 +++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 7 deletions(-) (limited to 'user_guide_src/source/libraries/email.rst') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 025d04b11..6dd546356 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -28,7 +28,19 @@ This example assumes you are sending the email from one of your :: - $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(); + $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 ========================= @@ -42,7 +54,12 @@ 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); + $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. @@ -175,7 +192,9 @@ comma-delimited list or an array:: :: - $list = array('one@example.com', 'two@example.com', 'three@example.com'); $this->email->to($list); + $list = array('one@example.com', 'two@example.com', 'three@example.com'); + + $this->email->to($list); $this->email->cc() ------------------ @@ -225,7 +244,16 @@ 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(); } + 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:: @@ -238,7 +266,10 @@ $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 } + if ( ! $this->email->send()) + { + // Generate error + } $this->email->attach() ---------------------- @@ -247,7 +278,11 @@ 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->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() ------------------------------- @@ -264,6 +299,13 @@ 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. + 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} -- cgit v1.2.3-24-g4f1b From d14717f6f20323bcc76729da85d6040bf2a44a44 Mon Sep 17 00:00:00 2001 From: Joseph Wensley Date: Wed, 5 Oct 2011 23:57:14 -0400 Subject: format email preferences table --- user_guide_src/source/libraries/email.rst | 106 ++++++++---------------------- 1 file changed, 26 insertions(+), 80 deletions(-) (limited to 'user_guide_src/source/libraries/email.rst') diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 6dd546356..759899242 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -80,86 +80,32 @@ 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. +=================== ====================== ============================ ======================================================================= +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 ======================== -- cgit v1.2.3-24-g4f1b