Email

Warning

Before version 3.1, the Email and Transport classes were underthe Cake\Network\Email namespace instead of the Cake\Mailernamespace.

  • class Cake\Mailer\Email(mixed $profile = null)
  • Email is a new class to send email. With thisclass you can send email from any place inside of your application.

Basic Usage

First of all, you should ensure the class is loaded:

  1. use Cake\Mailer\Email;

After you’ve loaded Email, you can send an email with the following:

  1. $email = new Email('default');
  2. $email->from(['me@example.com' => 'My Site'])
  3.     ->to('you@example.com')
  4.     ->subject('About')
  5.     ->send('My message');

Since Email’s setter methods return the instance of the class, you are able to set its properties with method chaining.

Email has several methods for defining recipients - to(), cc(),bcc(), addTo(), addCc() and addBcc(). The main difference beingthat the first three will overwrite what was already set and the latter will justadd more recipients to their respective field:

  1. $email = new Email();
  2. $email->to('to@example.com', 'To Example');
  3. $email->addTo('to2@example.com', 'To2 Example');
  4. // The email's To recipients are: to@example.com and to2@example.com
  5. $email->to('test@example.com', 'ToTest Example');
  6. // The email's To recipient is: test@example.com

Deprecated since version 3.4.0: Use setFrom(), setTo(), setCc() , setBcc() and setSubject() instead.

Choosing the Sender

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

  1. $email = new Email();
  2. $email->sender('app@example.com', 'MyApp emailer');

Note

It’s also a good idea to set the envelope sender when sending mail on anotherperson’s behalf. This prevents them from getting any messages aboutdeliverability.

Deprecated since version 3.4.0: Use setSender() instead.

Configuration

Configuration for Email defaults is created using config() andconfigTransport(). You should put your email presets in theconfig/app.php file. The config/app.default.php file is anexample of this file. It is not required to define email configuration inconfig/app.php. Email can be used without it and use the respectivemethods to set all configurations separately or load an array of configs.

By defining profiles and transports, you can keep your application code free ofconfiguration data, and avoid duplication that makes maintenance and deploymentmore difficult.

To load a predefined configuration, you can use the profile() method or pass itto the constructor of Email:

  1. $email = new Email();
  2. $email->profile('default');
  3.  
  4. // Or in constructor
  5. $email = new Email('default');

Instead of passing a string which matches a preset configuration name, you canalso just load an array of options:

  1. $email = new Email();
  2. $email->profile(['from' => 'me@example.org', 'transport' => 'my_custom']);
  3.  
  4. // Or in constructor
  5. $email = new Email(['from' => 'me@example.org', 'transport' => 'my_custom']);

Changed in version 3.1: The default email profile is automatically set when an Emailinstance is created.

Deprecated since version 3.4.0: Use setProfile() instead of profile().

Configuring Transports

  • static Cake\Mailer\Email::configTransport($key, $config)
  • Email messages are delivered by transports. Different transports allow you tosend messages via PHP’s mail() function, SMTP servers, or not at all whichis useful for debugging. Configuring transports allows you to keep configurationdata out of your application code and makes deployment simpler as you can simplychange the configuration data. An example transport configuration looks like:
  1. use Cake\Mailer\Email;
  2. use Cake\Mailer\TransportFactory;
  3.  
  4. // Sample Mail configuration
  5. // Prior to 3.7.0 use Email::configTransport()
  6. TransportFactory::setConfig('default', [
  7.     'className' => 'Mail'
  8. ]);
  9.  
  10. // Sample SMTP configuration.
  11. TransportFactory::setConfig('gmail', [
  12.     'host' => 'ssl://smtp.gmail.com',
  13.     'port' => 465,
  14.     'username' => 'my@gmail.com',
  15.     'password' => 'secret',
  16.     'className' => 'Smtp'
  17. ]);

You can configure SSL SMTP servers, like Gmail. To do so, put the ssl://prefix in the host and configure the port value accordingly. You can alsoenable TLS SMTP using the tls option:

  1. use Cake\Mailer\Email;
  2. use Cake\Mailer\TransportFactory;
  3.  
  4. TransportFactory::setConfig('gmail', [
  5.     'host' => 'smtp.gmail.com',
  6.     'port' => 587,
  7.     'username' => 'my@gmail.com',
  8.     'password' => 'secret',
  9.     'className' => 'Smtp',
  10.     'tls' => true
  11. ]);

The above configuration would enable TLS communication for email messages.

Warning

You will need to have access for less secure apps enabled in your Googleaccount for this to work:Allowing less secure apps to access youraccount.

Note

Gmail SMTP settings.

Note

To use SSL + SMTP, you will need to have the SSL configured in your PHPinstall.

Configuration options can also be provided as a DSN string. This isuseful when working with environment variables or PaaS providers:

  1. TransportFactory::setConfig('default', [
  2.     'url' => 'smtp://my@gmail.com:secret@smtp.gmail.com:587?tls=true',
  3. ]);
  4.  
  5. // Prior to 3.7.0 use
  6. Email::configTransport('default', [
  7.     'url' => 'smtp://my@gmail.com:secret@smtp.gmail.com:587?tls=true',
  8. ]);

When using a DSN string you can define any additional parameters/options asquery string arguments.

  • static Cake\Mailer\Email::dropTransport($key)
  • Once configured, transports cannot be modified. In order to modify a transportyou must first drop it and then reconfigure it.

Configuration Profiles

Defining delivery profiles allows you to consolidate common email settings intore-usable profiles. Your application can have as many profiles as necessary. Thefollowing configuration keys are used:

  • 'from': Email or array of sender. See Email::from().
  • 'sender': Email or array of real sender. See Email::sender().
  • 'to': Email or array of destination. See Email::to().
  • 'cc': Email or array of carbon copy. See Email::cc().
  • 'bcc': Email or array of blind carbon copy. See Email::bcc().
  • 'replyTo': Email or array to reply the e-mail. See Email::replyTo().
  • 'readReceipt': Email address or an array of addresses to receive thereceipt of read. See Email::readReceipt().
  • 'returnPath': Email address or an array of addresses to return if havesome error. See Email::returnPath().
  • 'messageId': Message ID of e-mail. See Email::messageId().
  • 'subject': Subject of the message. See Email::subject().
  • 'message': Content of message. Do not set this field if you are using rendered content.
  • 'priority': Priority of the email as numeric value (usually from 1 to 5 with 1 being the highest).
  • 'headers': Headers to be included. See Email::headers().
  • 'viewRender': If you are using rendered content, set the view classname.See Email::viewRender().
  • 'template': If you are using rendered content, set the template name. SeeEmail::template().
  • 'theme': Theme used when rendering template. See Email::theme().
  • 'layout': If you are using rendered content, set the layout to render. Ifyou want to render a template without layout, set this field to null. SeeEmail::template().
  • 'viewVars': If you are using rendered content, set the array withvariables to be used in the view. See Email::setViewVars().
  • 'attachments': List of files to attach. See Email::attachments().
  • 'emailFormat': Format of email (html, text or both). See Email::emailFormat().
  • 'transport': Transport configuration name. SeeMailer\Email::configTransport().
  • 'log': Log level to log the email headers and message. true will useLOG_DEBUG. See also Using Levels.
  • 'helpers': Array of helpers used in the email template. Email::helpers().
    All these configurations are optional, except 'from'.

Note

The values of above keys using Email or array, like from, to, cc, etc will be passedas first parameter of corresponding methods. The equivalent for:Email::from('my@example.com', 'My Site')would be defined as 'from' => ['my@example.com' => 'My Site'] in your config

Setting Headers

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

See Email::headers() and Email::addHeaders()

Deprecated since version 3.4.0: Use setHeaders() instead of headers().

Sending Templated Emails

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

The templates for emails reside in a special folder in your application’sTemplate directory called Email. Email views can also use layoutsand elements just like normal views:

  1. $email = new Email();
  2. $email
  3.     ->template('welcome', 'fancy')
  4.     ->emailFormat('html')
  5.     ->to('bob@example.com')
  6.     ->from('app@domain.com')
  7.     ->send();

The above would use src/Template/Email/html/welcome.ctp for the viewand src/Template/Layout/Email/html/fancy.ctp for the layout. You cansend multipart templated email messages as well:

  1. $email = new Email();
  2. $email
  3.     ->template('welcome', 'fancy')
  4.     ->emailFormat('both')
  5.     ->to('bob@example.com')
  6.     ->from('app@domain.com')
  7.     ->send();

This would use the following template files:

  • src/Template/Email/text/welcome.ctp
  • src/Template/Layout/Email/text/fancy.ctp
  • src/Template/Email/html/welcome.ctp
  • src/Template/Layout/Email/html/fancy.ctp
    When sending templated emails you have the option of sending eithertext, html or both.

You can set view variables with Email::setViewViars():

  1. $email = new Email('templated');
  2. $email->setViewVars(['value' => 12345]);

In your email templates you can use these with:

  1. <p>Here is your value: <b><?= $value ?></b></p>

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

  1. $email->helpers(['Html', 'Custom', 'Text']);

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

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

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

The above would use template and layout 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 Email to use appropriate theme usingEmail::theme() method:

  1. $email = new Email();
  2. $email->template('Blog.new_comment', 'Blog.auto_message');
  3. $email->theme('TestTheme');

This allows you to override the new_comment template in your theme withoutmodifying the Blog plugin. The template file needs to be created in thefollowing path:src/Template/Plugin/TestTheme/Plugin/Blog/Email/text/new_comment.ctp.

Deprecated since version 3.4.0: Use viewBuilder()->setTemplate() instead of template(). UseviewBuilder()->setLayout() instead of the layout argument oftemplate(). Use viewBuilder()->setTheme() instead of theme().

Sending Attachments

  • Cake\Mailer\Email::attachments($attachments)

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

  • String: $email->attachments('/full/file/path/file.png') will attach thisfile with the name file.png.

  • Array: $email->attachments(['/full/file/path/file.png']) will havethe same behavior as using a string.

  • Array with key:$email->attachments(['photo.png' => '/full/some_hash.png']) willattach some_hash.png with the name photo.png. The recipient will seephoto.png, not some_hash.png.

  • Nested arrays:

  1. $email->attachments([
  2.     'photo.png' => [
  3.         'file' => '/full/some_hash.png',
  4.         'mimetype' => 'image/png',
  5.         'contentId' => 'my-unique-id'
  6.     ]
  7. ]);

The above will attach the file with different mimetype and with customContent 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 HTMLbody like <img src="cid:my-content-id">.

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

4.3 Instead of the file option you can provide the file contents asa string using the data option. This allows you to attach files withoutneeding file paths to them.

Deprecated since version 3.4.0: Use setAttachments() instead of attachments().

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 Cake\Mailer\Email::transport()method or have the transport in your configuration:

  1. $email = new Email();
  2.  
  3. // Use a named transport already configured using Email::configTransport()
  4. $email->transport('gmail');
  5.  
  6. // Use a constructed object.
  7. $transport = new DebugTransport();
  8. $email->transport($transport);

Deprecated since version 3.4.0: Use setTransport() instead of transport().

Creating Custom Transports

You are able to create your custom transports to integrate with others emailsystems (like SwiftMailer). To create your transport, first create the filesrc/Mailer/Transport/ExampleTransport.php (where Example is the name of yourtransport). To start off your file should look like:

  1. namespace App\Mailer\Transport;
  2.  
  3. use Cake\Mailer\AbstractTransport;
  4. use Cake\Mailer\Email;
  5.  
  6. class ExampleTransport extends AbstractTransport
  7. {
  8.     public function send(Email $email)
  9.     {
  10.         // Do something.
  11.     }
  12. }

You must implement the method send(Email $email) with your custom logic.Optionally, you can implement the config($config) method. config() iscalled before send() and allows you to accept user configurations. By default,this method puts the configuration in protected attribute $_config.

If you need to call additional methods on the transport before send, you can useCake\Mailer\Email::getTransport() to get an instance of the transport object.Example:

  1. $yourInstance = $email->getTransport()->transportClass();
  2. $yourInstance->myCustomMethod();
  3. $email->send();

Relaxing Address Validation Rules

  • Cake\Mailer\Email::emailPattern($pattern)
  • If you are having validation issues when sending to non-compliant addresses, youcan relax the pattern used to validate email addresses. This is sometimesnecessary when dealing with some ISP’s:
  1. $email = new Email('default');
  2.  
  3. // Relax the email pattern, so you can send
  4. // to non-conformant addresses.
  5. $email->emailPattern($newPattern);

Deprecated since version 3.4.0: Use setEmailPattern() instead of emailPattern().

Sending Messages Quickly

Sometimes you need a quick way to fire off an email, and you don’t necessarilywant do setup a bunch of configuration ahead of time.Cake\Mailer\Email::deliver() is intended for that purpose.

You can create your configuration usingCake\Mailer\Email::config(), or use an array with alloptions that you need and use the static method Email::deliver().Example:

  1. Email::deliver('you@example.com', 'Subject', 'Message', ['from' => 'me@example.com']);

This method will send an email to “you@example.com”, from “me@example.com” withsubject “Subject” and content “Message”.

The return of deliver() is a Cake\Mailer\Email instance with allconfigurations set. If you do not want to send the email right away, and wishto configure a few things before sending, you can pass the 5th parameter asfalse.

The 3rd parameter is the content of message or an array with variables (whenusing rendered content).

The 4th parameter can be an array with the configurations or a string with thename of configuration in Configure.

If you want, you can pass the to, subject and message as null and do allconfigurations in the 4th parameter (as array or using Configure).Check the list of configurations to see all accepted configs.

Sending Emails from CLI

When sending emails within a CLI script (Shells, Tasks, …) you should manuallyset the domain name for Email to use. It will serve as the host name for themessage id (since there is no host name in a CLI environment):

  1. $email->domain('www.example.org');
  2. // Results in message ids like ``<UUID@www.example.org>`` (valid)
  3. // Instead of `<UUID@>`` (invalid)

A valid message id can help to prevent emails ending up in spam folders.

Deprecated since version 3.4.0: Use setDomain() instead of domain().

Creating Reusable Emails

New in version 3.1.0.

Mailers allow you to create reusable emails throughout your application. Theycan also be used to contain multiple email configurations in one location. Thishelps keep your code DRYer and keeps email configuration noise out of otherareas in your application.

In this example we will be creating a Mailer that contains user-relatedemails. To create our UserMailer, create the filesrc/Mailer/UserMailer.php. The contents of the file should look like thefollowing:

  1. namespace App\Mailer;
  2.  
  3. use Cake\Mailer\Mailer;
  4.  
  5. class UserMailer extends Mailer
  6. {
  7.     public function welcome($user)
  8.     {
  9.         $this
  10.             ->to($user->email)
  11.             ->subject(sprintf('Welcome %s', $user->name))
  12.             ->template('welcome_mail', 'custom'); // By default template with same name as method name is used.
  13.     }
  14.  
  15.     public function resetPassword($user)
  16.     {
  17.         $this
  18.             ->to($user->email)
  19.             ->subject('Reset password')
  20.             ->set(['token' => $user->token]);
  21.     }
  22. }

In our example we have created two methods, one for sending a welcome email, andanother for sending a password reset email. Each of these methods expect a userEntity and utilizes its properties for configuring each email.

We are now able to use our UserMailer to send out our user-related emailsfrom anywhere in our application. For example, if we wanted to send our welcomeemail we could do the following:

  1. namespace App\Controller;
  2.  
  3. use Cake\Mailer\MailerAwareTrait;
  4.  
  5. class UsersController extends AppController
  6. {
  7.     use MailerAwareTrait;
  8.  
  9.     public function register()
  10.     {
  11.         $user = $this->Users->newEntity();
  12.         if ($this->request->is('post')) {
  13.             $user = $this->Users->patchEntity($user, $this->request->getData())
  14.             if ($this->Users->save($user)) {
  15.                 $this->getMailer('User')->send('welcome', [$user]);
  16.             }
  17.         }
  18.         $this->set('user', $user);
  19.     }
  20. }

If we wanted to completely separate sending a user their welcome email from ourapplication’s code, we can have our UserMailer subscribe to theModel.afterSave event. By subscribing to an event, we can keep ourapplication’s user-related classes completely free of email-related logic andinstructions. For example, we could add the following to our UserMailer:

  1. public function implementedEvents()
  2. {
  3.     return [
  4.         'Model.afterSave' => 'onRegistration'
  5.     ];
  6. }
  7.  
  8. public function onRegistration(Event $event, EntityInterface $entity, ArrayObject $options)
  9. {
  10.     if ($entity->isNew()) {
  11.         $this->send('welcome', [$entity]);
  12.     }
  13. }

The mailer object could now be registered as an event listener, and theonRegistration() method would be invoked every time the Model.afterSaveevent would be fired. For information on how to register event listener objects,please refer to the Registering Listeners documentation.

Testing Email

To test email, add Cake\TestSuite\EmailTrait to your test case.The EmailTrait provides your test case with a collection of assertionsthat you can perform on any emails sent by the application.

Adding the EmailTrait to your test case will replace all of your application’semail transports with the Cake\TestSuite\TestEmailTransport. This transportintercepts emails instead of sending them, and allows you to assert against them.

Add the trait to your test case to start testing emails:

  1. namespace App\Test\TestCase;
  2.  
  3. use Cake\TestSuite\EmailTrait;
  4.  
  5. class MyTestCase extends TestCase
  6. {
  7.     use EmailTrait;
  8. }

New in version 3.7.0: Cake\TestSuite\EmailTrait was added.

Assertion methods

The Cake\TestSuite\EmailTrait trait provides the following assertions:

  1. // Asserts an expected number of emails were sent
  2. $this->assertMailCount($count);
  3.  
  4. // Asserts that no emails were sent
  5. $this->assertNoMailSent();
  6.  
  7. // Asserts an email was sent to an address
  8. $this->assertMailSentTo($address);
  9.  
  10. // Asserts an email was sent from an address
  11. $this->assertMailSentFrom($address);
  12.  
  13. // Asserts an email contains expected contents
  14. $this->assertMailContains($contents);
  15.  
  16. // Asserts an email contains expected html contents
  17. $this->assertMailContainsHtml($contents);
  18.  
  19. // Asserts an email contains expected text contents
  20. $this->assertMailContainsText($contents);
  21.  
  22. // Asserts an email contains the expected value within an Email getter (e.g., "subject")
  23. $this->assertMailSentWith($expected, $parameter);
  24.  
  25. // Asserts an email at a specific index was sent to an address
  26. $this->assertMailSentToAt($at, $address);
  27.  
  28. // Asserts an email at a specific index was sent from an address
  29. $this->assertMailSentFromAt($at, $address);
  30.  
  31. // Asserts an email at a specific index contains expected contents
  32. $this->assertMailContainsAt($at, $contents);
  33.  
  34. // Asserts an email at a specific index contains expected html contents
  35. $this->assertMailContainsHtmlAt($at, $contents);
  36.  
  37. // Asserts an email at a specific index contains expected text contents
  38. $this->assertMailContainsTextAt($at, $contents);
  39.  
  40. // Asserts an email at a specific index contains the expected value within an Email getter (e.g., "subject")
  41. $this->assertMailSentWithAt($at, $expected, $parameter);