+ +
+

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
    • +
+ +
+

Using the Email Library

+
+

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 +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();
+
+
+
+
+

Setting Email Preferences

+

There are 21 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 method. 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() method 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.

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PreferenceDefault ValueOptionsDescription
useragentCodeIgniterNoneThe “user agent”.
protocolmailmail, sendmail, or smtpThe mail sending protocol.
mailpath/usr/sbin/sendmailNoneThe server path to Sendmail.
smtp_hostNo DefaultNoneSMTP Server Address.
smtp_userNo DefaultNoneSMTP Username.
smtp_passNo DefaultNoneSMTP Password.
smtp_port25NoneSMTP Port.
smtp_timeout5NoneSMTP Timeout (in seconds).
smtp_keepaliveFALSETRUE or FALSE (boolean)Enable persistent SMTP connections.
smtp_cryptoNo Defaulttls or sslSMTP Encryption
wordwrapTRUETRUE or FALSE (boolean)Enable word-wrap.
wrapchars76 Character count to wrap at.
mailtypetexttext or htmlType 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$config['charset'] Character set (utf-8, iso-8859-1, etc.).
validateFALSETRUE or FALSE (boolean)Whether to validate the email address.
priority31, 2, 3, 4, 5Email 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_modeFALSETRUE or FALSE (boolean)Enable BCC Batch Mode.
bcc_batch_size200NoneNumber of emails in each BCC batch.
dsnFALSETRUE or FALSE (boolean)Enable notify message from server
+
+
+

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}

+
+
+
+

Class Reference

+
+
+class CI_Email
+
+
+from($from[, $name = ''[, $return_path = NULL]])
+
+++ + + + + + + + +
Parameters:
    +
  • $from (string) – “From” e-mail address
    • +
  • $name (string) – “From” display name
    • +
  • $return_path (string) – Optional email address to redirect undelivered e-mail to
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the email address and name of the person sending the email:

+
$this->email->from('you@example.com', 'Your Name');
+
+
+

You can also set a Return-Path, to help redirect undelivered mail:

+
$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.

+
+
+ +
+
+reply_to($replyto[, $name = ''])
+
+++ + + + + + + + +
Parameters:
    +
  • $replyto (string) – E-mail address for replies
    • +
  • $name (string) – Display name for the reply-to e-mail address
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the reply-to address. If the information is not provided the +information in the :meth:from method is used. Example:

+
$this->email->reply_to('you@example.com', 'Your Name');
+
+
+
+ +
+
+to($to)
+
+++ + + + + + + + +
Parameters:
    +
  • $to (mixed) – Comma-delimited string or an array of e-mail addresses
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the email address(s) of the recipient(s). Can be a single e-mail, +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');
+
+
+
$this->email->to(
+        array('one@example.com', 'two@example.com', 'three@example.com')
+);
+
+
+
+ +
+
+cc($cc)
+
+++ + + + + + + + +
Parameters:
    +
  • $cc (mixed) – Comma-delimited string or an array of e-mail addresses
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the CC email address(s). Just like the “to”, can be a single e-mail, +a comma-delimited list or an array.

+
+ +
+
+bcc($bcc[, $limit = ''])
+
+++ + + + + + + + +
Parameters:
    +
  • $bcc (mixed) – Comma-delimited string or an array of e-mail addresses
    • +
  • $limit (int) – Maximum number of e-mails to send per batch
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the BCC email address(s). Just like the to() method, can be a single +e-mail, a comma-delimited list or an array.

+

If $limit is set, “batch mode” will be enabled, which will send +the emails to batches, with each batch not exceeding the specified +$limit.

+
+ +
+
+subject($subject)
+
+++ + + + + + + + +
Parameters:
    +
  • $subject (string) – E-mail subject line
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the email subject:

+
$this->email->subject('This is my subject');
+
+
+
+ +
+
+message($body)
+
+++ + + + + + + + +
Parameters:
    +
  • $body (string) – E-mail message body
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the e-mail message body:

+
$this->email->message('This is my message');
+
+
+
+ +
+
+set_alt_message($str)
+
+++ + + + + + + + +
Parameters:
    +
  • $str (string) – Alternative e-mail message body
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Sets the alternative e-mail 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.

+
+ +
+
+set_header($header, $value)
+
+++ + + + + + + + +
Parameters:
    +
  • $header (string) – Header name
    • +
  • $value (string) – Header value
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

Appends additional headers to the e-mail:

+
$this->email->set_header('Header1', 'Value1');
+$this->email->set_header('Header2', 'Value2');
+
+
+
+ +
+
+clear([$clear_attachments = FALSE])
+
+++ + + + + + + + +
Parameters:
    +
  • $clear_attachments (bool) – Whether or not to clear attachments
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

CI_Email

+
+

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.

+
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);
+
+
+
+ +
+
+send([$auto_clear = TRUE])
+
+++ + + + + + + + +
Parameters:
    +
  • $auto_clear (bool) – Whether to clear message data automatically
    • +
+
Returns:

TRUE on success, FALSE on failure

+
Return type:

bool

+
+

The e-mail 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.

+
+
+ +
+
+attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])
+
+++ + + + + + + + +
Parameters:
    +
  • $filename (string) – File name
    • +
  • $disposition (string) – ‘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
    • +
  • $newname (string) – Custom file name to use in the e-mail
    • +
  • $mime (string) – MIME type to use (useful for buffered data)
    • +
+
Returns:

CI_Email instance (method chaining)

+
Return type:

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 parameter:

+
$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');
+
+
+
+ +
+
+attachment_cid($filename)
+
+++ + + + + + + + +
Parameters:
    +
  • $filename (string) – Existing attachment filename
    • +
+
Returns:

Attachment Content-ID or FALSE if not found

+
Return type:

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->attachment_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.

+
+
+ +
+
+print_debugger([$include = array('headers', 'subject', 'body')])
+
+++ + + + + + + + +
Parameters:
    +
  • $include (array) – Which parts of the message to print out
    • +
+
Returns:

Formatted debug data

+
Return type:

string

+
+

Returns a string containing any server messages, the email headers, and +the email message. 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'));
+
+
+
+

Note

+

By default, all of the raw data will be printed.

+
+
+ +
+ +
+
+ + +