summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/email.rst
diff options
context:
space:
mode:
Diffstat (limited to 'user_guide_src/source/libraries/email.rst')
-rw-r--r--user_guide_src/source/libraries/email.rst374
1 files changed, 234 insertions, 140 deletions
diff --git a/user_guide_src/source/libraries/email.rst b/user_guide_src/source/libraries/email.rst
index 39629ece1..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,206 +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. Note: Use a file path, not a URL. 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');
-If you'd like to use a custom file name, you can use the third paramater::
+ .. method:: clear([$clear_attachments = FALSE])
- $this->email->attach('filename.pdf', 'attachment', 'report.pdf');
+ :param bool $clear_attachments: Whether or not to clear attachments
+ :returns: CI_Email instance (method chaining)
+ :rtype: CI_Email
-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::
+ 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($buffer, 'attachment', 'report.pdf', 'application/pdf');
+ ::
-$this->email->print_debugger()
-------------------------------
+ foreach ($list as $name => $address)
+ {
+ $this->email->clear();
-Returns a string containing any server messages, the email headers, and
-the email messsage. Useful for debugging.
+ $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();
+ }
-You can optionally specify which parts of the message should be printed.
-Valid options are: **headers**, **subject**, **body**.
+ If you set the parameter to TRUE any attachments will be cleared as
+ well::
-Example::
+ $this->email->clear(TRUE);
- // 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);
+ .. method:: send([$auto_clear = TRUE])
- // Will only print the email headers, excluding the message subject and body
- $this->email->print_debugger(array('headers'));
+ :param bool $auto_clear: Whether to clear message data automatically
+ :returns: TRUE on success, FALSE on failure
+ :rtype: bool
-.. note:: By default, all of the raw data will be printed.
+ The e-mail sending method. Returns boolean TRUE or FALSE based on
+ success or failure, enabling it to be used conditionally::
-Overriding Word Wrapping
-========================
+ if ( ! $this->email->send())
+ {
+ // Generate error
+ }
-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::
+ This method will automatically clear all parameters if the request was
+ successful. To stop this behaviour pass FALSE::
- The text of your email that
- gets wrapped normally.
+ if ($this->email->send(FALSE))
+ {
+ // Parameters won't be cleared
+ }
- {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}
+ .. note:: In order to use the ``print_debugger()`` method, you need
+ to avoid clearing the email parameters.
- More text that will be
- wrapped normally.
-
+ .. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])
+
+ :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
+
+ 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::
+
+ $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');
+
+ 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