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 smallBCC batches.
• Email Debugging tools

• Using the Email Library
  • Sending Email
  • Setting Email Preferences
  • Email Preferences
  • Overriding Word Wrapping
• Class Reference

Using the Email Library

Sending Email

Sending email is not only simple, but you can configure it on the fly orset your preferences in the app/Config/Email.php file.

Here is a basic example demonstrating how you might send email:

$email = \Config\Services::email();
 
$email->setFrom('your@example.com', 'Your Name');
$email->setTo('someone@example.com');
$email->setCC('another@another-example.com');
$email->setBCC('them@their-example.com');
 
$email->setSubject('Email Test');
$email->setMessage('Testing the email class.');
 
$email->send();

Setting Email Preferences

There are 21 different preferences available to tailor how your emailmessages are sent. You can either set them manually as described here,or automatically via preferences stored in your config file, describedbelow:

Preferences are set by passing an array of preference values to theemail initialize method. Here is an example of how you might set somepreferences:

$config['protocol'] = 'sendmail';
$config['mailPath'] = '/usr/sbin/sendmail';
$config['charset']  = 'iso-8859-1';
$config['wordWrap'] = true;
 
$email->initialize($config);

Note

Most of the preferences have default values that will be usedif you do not set them.

Setting Email Preferences in a Config File

If you prefer not to set preferences using the above method, you caninstead put them into the config file. Simply open theapp/Config/Email.php file, and set your configs in theEmail properties. Then save the file and it will be used automatically.You will NOT need to use the $email->initialize() method ifyou set your preferences in the config file.

Email Preferences

The following is a list of all the preferences that can be set whensending email.

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 yourmessage 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

• CodeIgniter\Email\Email
• • setFrom($from[, $name = ''[, $returnPath = null]])

Parameters:

- **$from** (_string_) – “From” e-mail address
- **$name** (_string_) – “From” display name
- **$returnPath** (_string_) – Optional email address to redirect undelivered e-mail toReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

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

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

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

$email->setFrom('you@example.com', 'Your Name', 'returned_emails@example.com');

Note

Return-Path can’t be used if you’ve configured ‘smtp’ asyour protocol.

• setReplyTo($replyto[, $name = ''])

Parameters:

- **$replyto** (_string_) – E-mail address for replies
- **$name** (_string_) – Display name for the reply-to e-mail addressReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Sets the reply-to address. If the information is not provided theinformation in the setFrom method is used. Example:

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

• setTo($to)

Parameters:

- **$to** (_mixed_) – Comma-delimited string or an array of e-mail addressesReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Sets the email address(s) of the recipient(s). Can be a single e-mail,a comma-delimited list or an array:

$email->setTo('someone@example.com');

$email->setTo('one@example.com, two@example.com, three@example.com');

$email->setTo(['one@example.com', 'two@example.com', 'three@example.com']);

• setCC($cc)

Parameters:

- **$cc** (_mixed_) – Comma-delimited string or an array of e-mail addressesReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

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

• setBCC($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 batchReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

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

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

• setSubject($subject)

Parameters:

- **$subject** (_string_) – E-mail subject lineReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Sets the email subject:

$email->setSubject('This is my subject');

• setMessage($body)

Parameters:

- **$body** (_string_) – E-mail message bodyReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Sets the e-mail message body:

$email->setMessage('This is my message');

• setAltMessage($str)

Parameters:

- **$str** (_string_) – Alternative e-mail message bodyReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Sets the alternative e-mail message body:

$email->setAltMessage('This is the alternative message');

This is an optional message string which can be used if you sendHTML formatted email. It lets you specify an alternative messagewith no HTML formatting which is added to the header string forpeople who do not accept HTML email. If you do not set your ownmessage CodeIgniter will extract the message from your HTML emailand strip the tags.

• setHeader($header, $value)

Parameters:

- **$header** (_string_) – Header name
- **$value** (_string_) – Header valueReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Appends additional headers to the e-mail:

$email->setHeader('Header1', 'Value1');
$email->setHeader('Header2', 'Value2');

• clear($clearAttachments = false)

Parameters:

- **$clearAttachments** (_bool_) – Whether or not to clear attachmentsReturns:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Initializes all the email variables to an empty state. This methodis 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)
{
        $email->clear();
 
        $email->setTo($address);
        $email->setFrom('your@example.com');
        $email->setSubject('Here is your info '.$name);
        $email->setMessage('Hi ' . $name . ' Here is the info you requested.');
        $email->send();
}

If you set the parameter to TRUE any attachments will be cleared aswell:

$email->clear(true);

• send($autoClear = true)

Parameters:

- **$autoClear** (_bool_) – Whether to clear message data automaticallyReturns:

TRUE on success, FALSE on failureReturn type:bool

The e-mail sending method. Returns boolean TRUE or FALSE based onsuccess or failure, enabling it to be used conditionally:

if (! $email->send())
{
        // Generate error
}

This method will automatically clear all parameters if the request wassuccessful. To stop this behaviour pass FALSE:

if ($email->send(false))
{
        // Parameters won't be cleared
}

Note

In order to use the printDebugger() method, you needto avoid clearing the email parameters.

Note

If BCCBatchMode is enabled, and there are more thanBCCBatchSize recipients, this method will always returnboolean TRUE.

• attach($filename[, $disposition = ''[, $newname = null[, $mime = '']]])

Parameters:

- **$filename** (_string_) – File name
- **$disposition** (_string_) – ‘disposition’ of the attachment. Mostemail clients make their own decision regardless of the MIMEspecification used here. [https://www.iana.org/assignments/cont-disp/cont-disp.xhtml](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:

CodeIgniter\Email\Email instance (method chaining)Return type:CodeIgniter\Email\Email

Enables you to send an attachment. Put the file path/name in the firstparameter. For multiple attachments use the method multiple times.For example:

$email->attach('/path/to/photo1.jpg');
$email->attach('/path/to/photo2.jpg');
$email->attach('/path/to/photo3.jpg');

To use the default disposition (attachment), leave the second parameter blank,otherwise use a custom disposition:

$email->attach('image.jpg', 'inline');

You can also use a URL:

$email->attach('http://example.com/filename.pdf');

If you’d like to use a custom file name, you can use the third parameter:

$email->attach('filename.pdf', 'attachment', 'report.pdf');

If you need to use a buffer string instead of a real - physical - file you canuse the first parameter as buffer, the third parameter as file name and the fourthparameter as mime-type:

$email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');

• setAttachmentCID($filename)

Parameters:

- **$filename** (_string_) – Existing attachment filenameReturns:

Attachment Content-ID or FALSE if not foundReturn 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';
$email->attach($filename);
foreach ($list as $address)
{
        $email->setTo($address);
        $cid = $email->setAttachmentCID($filename);
        $email->setMessage('<img src="cid:'. $cid .'" alt="photo1" />');
        $email->send();
}

Note

Content-ID for each e-mail must be re-created for it to be unique.

• printDebugger($include = ['headers', 'subject', 'body'])

Parameters:

- **$include** (_array_) – Which parts of the message to print outReturns:

Formatted debug dataReturn type:string

Returns a string containing any server messages, the email headers, andthe 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, printDebugger() would have
// nothing to output.
$email->send(false);
 
// Will only print the email headers, excluding the message subject and body
$email->printDebugger(['headers']);

Note

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