diff options
Diffstat (limited to 'user_guide_src/source/libraries/email.rst')
| -rw-r--r-- | user_guide_src/source/libraries/email.rst | 390 |
1 files changed, 230 insertions, 160 deletions
diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst index 86f440a74..ebfde809b 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,230 +117,289 @@ 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" e-mail address + :param string $name: "From" display name + :param string $return_path: Optional email address to redirect undelivered e-mail to + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - $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); + .. method:: reply_to($replyto[, $name = '']) -$this->email->cc() ------------------- + :param string $replyto: E-mail address for replies + :param string $name: Display name for the reply-to e-mail address + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -Sets the CC email address(s). Just like the "to", can be a single email, -a comma-delimited list or an array. + Sets the reply-to address. If the information is not provided the + information in the :meth:from method is used. Example:: -$this->email->bcc() -------------------- + $this->email->reply_to('you@example.com', 'Your Name'); -Sets the BCC email address(s). Just like the "to", can be a single -email, a comma-delimited list or an array. + .. method:: to($to) -$this->email->subject() ------------------------ + :param mixed $to: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -Sets the email subject:: + Sets the email address(s) of the recipient(s). Can be a single e-mail, + a comma-delimited list or an array:: - $this->email->subject('This is my subject'); + $this->email->to('someone@example.com'); -$this->email->message() ------------------------ + :: -Sets the email message body:: + $this->email->to('one@example.com, two@example.com, three@example.com'); - $this->email->message('This is my message'); + :: -$this->email->set_alt_message() -------------------------------- + $this->email->to( + array('one@example.com', 'two@example.com', 'three@example.com') + ); -Sets the alternative email message body:: + .. method:: cc($cc) - $this->email->set_alt_message('This is the alternative message'); + :param mixed $cc: Comma-delimited string or an array of e-mail addresses + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -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. + Sets the CC email address(s). Just like the "to", can be a single e-mail, + a comma-delimited list or an array. -$this->email->set_header() --------------------------- + .. method:: bcc($bcc[, $limit = '']) -Appends additional headers to the e-mail:: + :param mixed $bcc: Comma-delimited string or an array of e-mail addresses + :param int $limit: Maximum number of e-mails to send per batch + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - $this->email->set_header('Header1', 'Value1'); - $this->email->set_header('Header2', 'Value2'); + Sets the BCC email address(s). Just like the ``to()`` method, can be a single + e-mail, a comma-delimited list or an array. -$this->email->clear() ---------------------- + If ``$limit`` is set, "batch mode" will be enabled, which will send + the emails to batches, with each batch not exceeding the specified + ``$limit``. -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:: subject($subject) -:: + :param string $subject: E-mail subject line + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - foreach ($list as $name => $address) - { - $this->email->clear(); + Sets the email subject:: - $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(); - } + $this->email->subject('This is my subject'); -If you set the parameter to TRUE any attachments will be cleared as -well:: + .. method:: message($body) - $this->email->clear(TRUE); + :param string $body: E-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -$this->email->send() --------------------- + Sets the e-mail message body:: -The Email sending method. Returns boolean TRUE or FALSE based on -success or failure, enabling it to be used conditionally:: + $this->email->message('This is my message'); - if ( ! $this->email->send()) - { - // Generate error - } + .. method:: set_alt_message($str) -This method will automatically clear all parameters if the request was -successful. To stop this behaviour pass FALSE:: + :param string $str: Alternative e-mail message body + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - if ($this->email->send(FALSE)) - { - // Parameters won't be cleared - } + Sets the alternative e-mail message body:: -.. note:: In order to use the ``print_debugger()`` method, you need - to avoid clearing the email parameters. + $this->email->set_alt_message('This is the alternative message'); -$this->email->attach() ----------------------- + 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. -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:: + .. method:: set_header($header, $value) - $this->email->attach('/path/to/photo1.jpg'); - $this->email->attach('/path/to/photo2.jpg'); - $this->email->attach('/path/to/photo3.jpg'); + :param string $header: Header name + :param string $value: Header value + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -To use the default disposition (attachment), leave the second parameter blank, -otherwise use a custom disposition:: + Appends additional headers to the e-mail:: - $this->email->attach('image.jpg', 'inline'); + $this->email->set_header('Header1', 'Value1'); + $this->email->set_header('Header2', 'Value2'); -You can use URL:: + .. method:: clear([$clear_attachments = FALSE]) - $this->email->attach('http://example.com/filename.pdf'); + :param bool $clear_attachments: Whether or not to clear attachments + :returns: CI_Email instance (method chaining) + :rtype: CI_Email -If you'd like to use a custom file name, you can use the third paramater:: + 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. - $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:: + foreach ($list as $name => $address) + { + $this->email->clear(); - $this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf'); + $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(); + } -$this->email->attachment_cid() ------------------------------- - -Sets and returns an attachment's Content-ID, which enables your to embed an inline -(picture) attachment into HTML. First parameter must be attached file. - -:: - - $filename = '/img/photo1.jpg'; - $this->email->attach($filename); - foreach ($list as $address) - { - $this->email->to($address); - $cid = $this->email->attach_cid($filename); - $this->email->message('<img src='cid:". $cid ."' alt="photo1" />'); - $this->email->send(); - } + If you set the parameter to TRUE any attachments will be cleared as + well:: -CID for each Email have to be create again to be unique. + $this->email->clear(TRUE); -$this->email->print_debugger() ------------------------------- + .. method:: send([$auto_clear = TRUE]) -Returns a string containing any server messages, the email headers, and -the email messsage. Useful for debugging. + :param bool $auto_clear: Whether to clear message data automatically + :returns: TRUE on success, FALSE on failure + :rtype: bool -You can optionally specify which parts of the message should be printed. -Valid options are: **headers**, **subject**, **body**. + The e-mail sending method. Returns boolean TRUE or FALSE based on + success or failure, enabling it to be used conditionally:: -Example:: + if ( ! $this->email->send()) + { + // Generate error + } - // 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 method will automatically clear all parameters if the request was + successful. To stop this behaviour pass FALSE:: - // Will only print the email headers, excluding the message subject and body - $this->email->print_debugger(array('headers')); + if ($this->email->send(FALSE)) + { + // Parameters won't be cleared + } -.. note:: By default, all of the raw data will be printed. + .. note:: In order to use the ``print_debugger()`` method, you need + to avoid clearing the email parameters. -Overriding Word Wrapping -======================== + .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]]) -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:: + :param string $filename: File name + :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 file name to use in the e-mail + :param string $mime: MIME type to use (useful for buffered data) + :returns: CI_Email instance (method chaining) + :rtype: CI_Email - The text of your email that - gets wrapped normally. + 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:: - {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap} + $this->email->attach('/path/to/photo1.jpg'); + $this->email->attach('/path/to/photo2.jpg'); + $this->email->attach('/path/to/photo3.jpg'); - More text that will be - wrapped normally. - + 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 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:: attachment_cid($filename) + + :param string $filename: Existing attachment filename + :returns: Attachment Content-ID or FALSE if not found + :rtype: 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->attach_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. + + .. method:: print_debugger([$include = array('headers', 'subject', 'body')]) + + :param array $include: Which parts of the message to print out + :returns: Formatted debug data + :rtype: 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 |