ExpressionEngine

2.11.9 User Guide

Retired Documentation

You are using the documentation for version 2.11.9. Go here for the latest version or check here for your available upgrades to the latest version.

Email Class

Calling the Email Class

class Email

ExpressionEngine uses the Email class for the sending of email via whatever protocol is specified in the site’s Email Preferences. This class is a library, so you have to load the Email library before using it:

ee()->load->library('email');

Sending an Email

The Email class will automatically create all email headers and will process the data in various ways depending on the parameters set (ex: word wrapping and email validity). So, you simply have to send the class the relevant information and it will take care of the rest. Below is an example piece of code used for sending a single email.

ee()->load->library('email');
ee()->load->helper('text');

ee()->email->wordwrap = true;
ee()->email->mailtype = 'text';
ee()->email->from($from);
ee()->email->to($recipient);
ee()->email->subject($email_subject);
ee()->email->message(entities_to_ascii($email_msg));
ee()->email->Send();

Properties

property Email::$charset

Specifies the character set of the email. Since ExpressionEngine uses the character set in the Control Panel and in the default templates, the default is set for UTF-8. However, in certain circumstances you might wish to change this.

Note

There are email clients that will ignore any character specified in an email and will attempt to auto-detect, sometimes erroneously.

property Email::$debug

Specifies whether to enable debugging mode for the class. If emails are not being sent, then it might be prudent to set this to TRUE and see if any errors are being sent by the Email class.

property Email::$mailtype

Specifies whether to send this email as a simple text email or an HTML email. The default type is 'text', so you only need to set this parameter when sending HTML email ('html').

property Email::$validate

Specifies whether to validate all emails sent to the class. By default this is FALSE, and it must be set to TRUE to perform the validation.

property Email::$wordwrap

Specifies whether the words in the email should be wrapped after a certain number of characters. By default, this is set to FALSE, so you only need to set its value if you want to use wordwrap.

property Email::$wrapchars

Specifies the number of characters to wrap at, if Email::$wordwrap is set to true.

Methods

Email::from($from[, $name = ''[, $return_path = NULL]])

The method for specifying the sender of the email:

ee()->email->from('you@example.com', 'Your Name');
Parameters:
  • $from (string) – The email address of the sender
  • $name (string) – The name of the sender
  • $return_path (string) – Email address to redirect undelivered mail
Returns:

Email class object
Return type:

Object
Email::reply_to($replyto[, $name = ''])

The method for specifying the Reply-To header of the email:

ee()->email->reply\_to('you@example.com', 'Your Name');
Parameters:
  • $replyto (string) – The email address for the reply-to
  • $name (string) – The name of the sender
Returns:

Email class object
Return type:

Object
Email::to($to)

The method for specifying the general recipient(s) of the email:

ee()->email->to('someone@example.com');
ee()->email->to('one@example.com, two@example.com, three@example.com');
Parameters:
  • $to (mixed) – Array or comma separated string of email addresses
Returns:

Email class object
Return type:

Object
Email::cc($cc)

The method for specifying the recipient(s) receiving a carbon copy of the email:

ee()->email->cc('someone@example.com');
Parameters:
  • $cc (mixed) – Array or comma separated string of email addresses
Returns:

Email class object
Return type:

Object
Email::bcc($bcc[, $limit = ''])

The method for specifying the recipient(s) receiving a blind carbon copy of the email:

ee()->email->bcc('someone@example.com', 200);
Parameters:
  • $bcc (mixed) – Array or comma separated string of email addresses
  • $limit (integer) – Number of emails to send at a time, will batch if necessary
Returns:

Email class object
Return type:

Object
Email::subject($subject)

Sets the email subject:

ee()->email->subject('This is my subject');
Parameters:
  • $subject (string) – Subject of the email
Returns:

Email class object
Return type:

Object
Email::message($body)

Sets the email message body:

ee()->email->message('This is my message');
Parameters:
  • $body (string) – The message body
Returns:

Email class object
Return type:

Object
Email::send_alt_message($str = '')

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:

ee()->email->set_alt_message('This is the alternative message');

Note

If you are using data from a channel entry and not sending an HTML email, then you should use the entities_to_ascii() method (text helper) to convert any HTML entities back into ASCII characters before sending the message to the class.

Parameters:
  • $str (string) – Alternative message with no HTML formatting sent to people who do not accept HTML email
Returns:

Email class object
Return type:

Object
Email::send($auto_clear = TRUE)

The Email sending method:

ee()->email->send();
Parameters:
  • $auto_clear (boolean) – When set to FALSE will prevent parameters from being cleared after sending the email
Returns:

TRUE if successful, FALSE otherwise
Return type:

Boolean

Note

In order to use the print_debugger() method, you need to avoid clearing the email parameters.

Email::print_debugger($include = array('headers', 'subject', 'body'))

Returns a string containing any server messages, the email headers, and the email message:

ee()->email->print_debugger();
Parameters:
  • $include (array) – Optionally specify which parts of the message should be printed. Valid options are: headers, subject, body.
Returns:

String of data requested
Return type:

String
Email::clear($clear_attachments = FALSE)

Clears out all parameters set either by property or method:

ee()->email->clear();
Parameters:
  • $clear_attachments (boolean) – If set to TRUE attachments will be cleared out, otherwise they’re left alone.
Returns:

Email class object
Return type:

Object

Sending Multiple Emails

If you are sending multiple emails in a method either for notifications or because each message has a separate message, then you should use the Email::clear method between each email to reset certain variables in the class. If you do not, then it is possible that the emails will not be sent or sent incorrectly:

ee()->load->library('email');
ee()->load->helper('text');

ee()->email->wordwrap = true;
ee()->email->mailtype = 'text';
$errors = array();

foreach($member_emails as $username => $from)
{
    ee()->email->from($from);
    ee()->email->to($recipient);
    ee()->email->subject("Account Expiration: {$username}");
    ee()->email->message(entities_to_ascii($message));
    ee()->email->send();

if ( ! ee()->email->send())
{
    $errors[] = ee()->email->print_debugger();

    // Send failed, data was not cleared
    ee()->email->clear();
}