CakeEmail¶

Choosing the sender¶

When sending email on behalf of other people it’s often a good idea to define the original sender using the Sender header. You can do so using sender():

$Email = new CakeEmail();
$Email->sender('[email protected]', 'MyApp emailer');

Configurations¶

The following configuration keys are used:

• 'from': Email or array of sender. See CakeEmail::from().

• 'sender': Email or array of real sender. See CakeEmail::sender().

• 'to': Email or array of destination. See CakeEmail::to().

• 'cc': Email or array of carbon copy. See CakeEmail::cc().

• 'bcc': Email or array of blind carbon copy. See CakeEmail::bcc().

• 'replyTo': Email or array to reply the e-mail. See CakeEmail::replyTo().

• 'readReceipt': Email address or an array of addresses to receive the receipt of read. See CakeEmail::readReceipt().

• 'returnPath': Email address or and array of addresses to return if have some error. See CakeEmail::returnPath().

• 'messageId': Message ID of e-mail. See CakeEmail::messageId().

• 'subject': Subject of the message. See CakeEmail::subject().

• 'message': Content of message. Do not set this field if you are using rendered content.

• 'headers': Headers to be included. See CakeEmail::setHeaders().

• 'viewRender': If you are using rendered content, set the view class name. See CakeEmail::viewRender().

• 'template': If you are using rendered content, set the template name. See CakeEmail::template().

• 'theme': Theme used when rendering template. See CakeEmail::theme().

• 'layout': If you are using rendered content, set the layout to render. If you want to render a template without layout, set this field to null. See CakeEmail::template().

• 'viewVars': If you are using rendered content, set the array with variables to be used in the view. See CakeEmail::viewVars().

• 'attachments': List of files to attach. See CakeEmail::attachments().

• 'emailFormat': Format of email (html, text or both). See CakeEmail::emailFormat().

• 'transport': Transport name. See CakeEmail::transport().

• 'helpers': Array of helpers used in the email template.

All of these configurations are optional, except 'from'. If you put more configurations in this array, the configurations will be used in the CakeEmail::config() method and passed to the transport class config(). For example, if you are using the SMTP transport, you should pass the host, port and other configurations.

Setting headers¶

In CakeEmail you are free to set whatever headers you want. When migrating to use CakeEmail, do not forget to put the X- prefix in your headers.

See CakeEmail::setHeaders() and CakeEmail::addHeaders()

Sending templated emails¶

Emails are often much more than just a simple text message. In order to facilitate that, CakePHP provides a way to send emails using CakePHP’s view layer.

The templates for emails reside in a special folder in your applications View directory called Emails. Email views can also use layouts, and elements just like normal views:

$Email = new CakeEmail();
$Email->template('welcome', 'fancy')
    ->emailFormat('html')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

The above would use app/View/Emails/html/welcome.ctp for the view, and app/View/Layouts/Emails/html/fancy.ctp for the layout. You can send multipart templated email messages as well:

$Email = new CakeEmail();
$Email->template('welcome', 'fancy')
    ->emailFormat('both')
    ->to('[email protected]')
    ->from('[email protected]')
    ->send();

This would use the following view files:

• app/View/Emails/text/welcome.ctp

• app/View/Layouts/Emails/text/fancy.ctp

• app/View/Emails/html/welcome.ctp

• app/View/Layouts/Emails/html/fancy.ctp

When sending templated emails you have the option of sending either text, html or both.

You can set view variables with CakeEmail::viewVars():

$Email = new CakeEmail('templated');
$Email->viewVars(array('value' => 12345));

In your email templates you can use these with:

<p>Here is your value: <b><?php echo $value; ?></b></p>

You can use helpers in emails as well, much like you can in normal view files. By default only the HtmlHelper is loaded. You can load additional helpers using the helpers() method:

$Email->helpers(array('Html', 'Custom', 'Text'));

When setting helpers be sure to include ‘Html’ or it will be removed from the helpers loaded in your email template.

If you want to send email using templates in a plugin you can use the familiar plugin syntax to do so:

$Email = new CakeEmail();
$Email->template('Blog.new_comment', 'Blog.auto_message');

The above would use templates from the Blog plugin as an example.

In some cases, you might need to override the default template provided by plugins. You can do this using themes by telling CakeEmail to use appropriate theme using CakeEmail::theme() method:

$Email = new CakeEmail();
$Email->template('Blog.new_comment', 'Blog.auto_message');
$Email->theme('TestTheme');

This allows you to override the new_comment template in your theme without modifying the Blog plugin. The template file needs to be created in the following path: APP/View/Themed/TestTheme/Blog/Emails/text/new_comment.ctp.

Sending attachments¶

CakeEmail::attachments($attachments = null)¶

You can attach files to email messages as well. There are a few different formats depending on what kind of files you have, and how you want the filenames to appear in the recipient’s mail client:

1. String: $Email->attachments('/full/file/path/file.png') will attach this file with the name file.png.

2. Array: $Email->attachments(array('/full/file/path/file.png')) will have the same behavior as using a string.

3. Array with key: $Email->attachments(array('photo.png' => '/full/some_hash.png')) will attach some_hash.png with the name photo.png. The recipient will see photo.png, not some_hash.png.

4. Nested arrays:

   $Email->attachments(array(
       'photo.png' => array(
           'file' => '/full/some_hash.png',
           'mimetype' => 'image/png',
           'contentId' => 'my-unique-id'
       )
   ));
   

   The above will attach the file with different mimetype and with custom Content ID (when set the content ID the attachment is transformed to inline). The mimetype and contentId are optional in this form.

   4.1. When you are using the contentId, you can use the file in the HTML body like <img src="cid:my-content-id">.

   4.2. You can use the contentDisposition option to disable the Content-Disposition header for an attachment. This is useful when sending ical invites to clients using outlook.

   4.3 Instead of the file option you can provide the file contents as a string using the data option. This allows you to attach files without needing file paths to them.

Using transports¶

Transports are classes designed to send the e-mail over some protocol or method. CakePHP supports the Mail (default), Debug and SMTP transports.

To configure your method, you must use the CakeEmail::transport() method or have the transport in your configuration.

App::uses('AbstractTransport', 'Network/Email');

class ExampleTransport extends AbstractTransport {

    public function send(CakeEmail $Email) {
        // magic inside!
    }

}

$yourInstance = $Email->transport('your')->transportClass();
$yourInstance->myCustomMethod();
$Email->send();

Relaxing address validation rules¶

CakeEmail::emailPattern($pattern = null)¶

If you are having validation issues when sending to non-compliant addresses, you can relax the pattern used to validate email addresses. This is sometimes necessary when dealing with some Japanese ISP’s:

$email = new CakeEmail('default');

// Relax the email pattern, so you can send
// to non-conformant addresses.
$email->emailPattern($newPattern);