diff options
Diffstat (limited to 'user_guide_src')
| -rw-r--r-- | user_guide_src/source/libraries/email.rst | 346 |
1 files changed, 206 insertions, 140 deletions
diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 39629ece1..1d9d2c171 100644 --- a/user_guide_src/source/libraries/email.rst +++ b/user_guide_src/source/libraries/email.rst @@ -16,6 +16,17 @@ CodeIgniter's robust Email Class supports the following features: BCC batches. - Email Debugging tools +.. contents:: + :local: + +.. raw:: html + + <div class="custom-index container"></div> + +*********************** +Using the Email Library +*********************** + Sending Email ============= @@ -31,12 +42,12 @@ 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->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->message('Testing the email class.'); $this->email->send(); @@ -83,7 +94,7 @@ Preference Default Value Options Descript =================== ====================== ============================ ======================================================================= **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. +**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. @@ -106,206 +117,261 @@ Preference Default Value Options Descript **dsn** FALSE TRUE or FALSE (boolean) Enable notify message from server =================== ====================== ============================ ======================================================================= -Email Methods Reference -======================= +Overriding Word Wrapping +======================== -$this->email->from() --------------------- +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:: -Sets the email address and name of the person sending the email:: + The text of your email that + gets wrapped normally. - $this->email->from('you@example.com', 'Your Name'); + {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} -You can also set a Return-Path, to help redirect undelivered mail:: + More text that will be + wrapped normally. - $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. -$this->email->reply_to() ------------------------- +Place the item you do not want word-wrapped between: {unwrap} {/unwrap} -Sets the reply-to address. If the information is not provided the -information in the "from" method is used. Example:: +*************** +Class Reference +*************** - $this->email->reply_to('you@example.com', 'Your Name'); +.. class:: CI_Email -$this->email->to() ------------------- + .. method:: from($from[, $name = ''[, $return_path = NULL]]) -Sets the email address(s) of the recipient(s). Can be a single email, a -comma-delimited list or an array:: + :param string $from: "From" email address + :param string $name: "From" display name + :param string $return_path: optional email address to redirect undelivered email + :returns: CI_Email object for method chaining - $this->email->to('someone@example.com'); + Sets the email address and name of the person sending the email:: -:: + $this->email->from('you@example.com', 'Your Name'); - $this->email->to('one@example.com, two@example.com, three@example.com'); + You can also set a Return-Path, to help redirect undelivered mail:: -:: + $this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com'); - $list = array('one@example.com', 'two@example.com', 'three@example.com'); + .. note:: Return-Path can't be used if you've configured 'smtp' as + your protocol. - $this->email->to($list); -$this->email->cc() ------------------- + .. method:: reply_to($replyto[, $name = '']) -Sets the CC email address(s). Just like the "to", can be a single email, -a comma-delimited list or an array. + :param string $replyto: email address for replies + :param string $name: display name for reply email address + :returns: CI_Email object for method chaining -$this->email->bcc() -------------------- + Sets the reply-to address. If the information is not provided the + information in the :meth:from method is used. Example:: -Sets the BCC email address(s). Just like the "to", can be a single -email, a comma-delimited list or an array. + $this->email->reply_to('you@example.com', 'Your Name'); -$this->email->subject() ------------------------ -Sets the email subject:: + .. method:: to($to) - $this->email->subject('This is my subject'); + :param mixed $to: comma delimited string or array of email addresses + :returns: CI_Email object for method chaining -$this->email->message() ------------------------ + Sets the email address(s) of the recipient(s). Can be a single email + , a comma-delimited list or an array:: -Sets the email message body:: + $this->email->to('someone@example.com'); - $this->email->message('This is my message'); + :: -$this->email->set_alt_message() -------------------------------- + $this->email->to('one@example.com, two@example.com, three@example.com'); -Sets the alternative email message body:: + :: - $this->email->set_alt_message('This is the alternative message'); + $list = array('one@example.com', 'two@example.com', 'three@example.com'); -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->to($list); -$this->email->set_header() --------------------------- -Appends additional headers to the e-mail:: + .. method:: cc($cc) - $this->email->set_header('Header1', 'Value1'); - $this->email->set_header('Header2', 'Value2'); + :param mixed $cc: comma delimited string or array of email addresses + :returns: CI_Email object for method chaining -$this->email->clear() ---------------------- + Sets the CC email address(s). Just like the "to", can be a single + email, a comma-delimited list or an array. -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. -:: + .. method:: bcc($bcc, $limit = '') - foreach ($list as $name => $address) - { - $this->email->clear(); + :param mixed $bcc: comma delimited string or array of email addresses + :param int $limit: Maximum number of emails to send per batch + :returns: CI_Email object for method chaining - $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(); - } + Sets the BCC email address(s). Just like the "to", can be a single + email, a comma-delimited list or an array. -If you set the parameter to TRUE any attachments will be cleared as -well:: + If ``$limit`` is set, "batch mode" will be enabled, which will send + the emails to batches, with each batch not exceeding the specified + ``$limit``. - $this->email->clear(TRUE); -$this->email->send() --------------------- + .. method:: subject($subject) -The Email sending method. Returns boolean TRUE or FALSE based on -success or failure, enabling it to be used conditionally:: + :param string $subject: email subject line + :returns: CI_Email object for method chaining - if ( ! $this->email->send()) - { - // Generate error - } + Sets the email subject:: -This method will automatically clear all parameters if the request was -successful. To stop this behaviour pass FALSE:: + $this->email->subject('This is my subject'); - 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. + .. method:: message($body) -$this->email->attach() ----------------------- + :param string $body: email body + :returns: CI_Email object for method chaining -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 method multiple times. For example:: + Sets the email message body:: - $this->email->attach('/path/to/photo1.jpg'); - $this->email->attach('/path/to/photo2.jpg'); - $this->email->attach('/path/to/photo3.jpg'); + $this->email->message('This is my message'); -To use the default disposition (attachment), leave the second parameter blank, -otherwise use a custom disposition:: - $this->email->attach('image.jpg', 'inline'); + .. method:: set_alt_message([$str = '']) -If you'd like to use a custom file name, you can use the third paramater:: + :param string $str: alternate email body + :returns: CI_Email object for method chaining - $this->email->attach('filename.pdf', 'attachment', 'report.pdf'); + Sets the alternative email message body:: -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->set_alt_message('This is the alternative message'); - $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + 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->print_debugger() ------------------------------- -Returns a string containing any server messages, the email headers, and -the email messsage. Useful for debugging. + .. method:: set_header($header, $value) -You can optionally specify which parts of the message should be printed. -Valid options are: **headers**, **subject**, **body**. + :param string $header: header name + :param string $value: header value + :returns: void -Example:: + Appends additional headers to the e-mail:: - // 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); + $this->email->set_header('Header1', 'Value1'); + $this->email->set_header('Header2', 'Value2'); - // 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. + .. method:: clear([$clear_attachments = FALSE]) -Overriding Word Wrapping -======================== + :param bool $clear_attachments: whether or not to clear attachments -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:: + 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. - The text of your email that - gets wrapped normally. + :: - {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} + foreach ($list as $name => $address) + { + $this->email->clear(); - More text that will be - wrapped normally. - + $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); + + + .. method:: send([$auto_clear = TRUE]) + + :param bool $auto_clear: Whether to :meth:clear automatically + :returns: bool + + The Email 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. + + + .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) + + :param string $filename: name of the file + :param string $disposition: '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 + :param string $newname: custom name to use for the file in the email + :param string $mime: MIME type to use (useful for buffered data) + :returns: CI_Email object for method chaining + + 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 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'); + + If you'd like to use a custom file name, you can use the third paramater:: + + $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'); + + + .. method:: print_debugger([$include = array('headers', 'subject', 'body')]) + + :param array $include: Which parts of the message to print out + :returns: string + + Returns a string containing any server messages, the email headers, and + the email messsage. 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')); -Place the item you do not want word-wrapped between: {unwrap} {/unwrap}
\ No newline at end of file + .. note:: By default, all of the raw data will be printed.
\ No newline at end of file |