Class Email

CakePHP Email class.

This class is used for sending Internet Message Format based on the standard outlined in https://www.rfc-editor.org/rfc/rfc2822.txt

Configuration

Configuration for Email is managed by Email::config() and Email::configTransport(). Email::config() can be used to add or read a configuration profile for Email instances. Once made configuration profiles can be used to re-use across various email messages your application sends.

Namespace: Cake\Mailer

Constants

string

EMAIL_PATTERN ¶

'/^((?:[\\p{L}0-9.!#$%&\'*+\\/=?^_`{|}~-]+)*@[\\p{L}0-9-._]+)$/ui'

Holds the regex pattern for email validation

int

LINE_LENGTH_MUST ¶
```
998
```
Line length - no must more - RFC 2822 - 2.1.1
int

LINE_LENGTH_SHOULD ¶
```
78
```
Line length - no should more - RFC 2822 - 2.1.1
string

MESSAGE_HTML ¶
```
'html'
```
Type of message - HTML
string

MESSAGE_TEXT ¶
```
'text'
```
Type of message - TEXT

Property Summary

$_appCharset protected

string|null

The application wide charset, used to encode headers and body
$_attachments protected

array

List of files that should be attached to the email.
$_bcc protected

array

Blind Carbon Copy
$_boundary protected

string|null

If set, boundary to use for multipart mime messages
$_cc protected

array

Carbon Copy
$_charset8bit protected

array

8Bit character sets
$_config protected static

array

Configuration sets.
$_contentTypeCharset protected

array

Define Content-Type charset name
$_domain protected

string

Domain for messageId generation. Needs to be manually set for CLI mailing as env('HTTP_HOST') is empty
$_dsnClassMap protected static deprecated

array

An array mapping url schemes to fully qualified Transport class names. Unused.
$_emailFormat protected

string

What format should the email be sent in
$_emailFormatAvailable protected

array

Available formats to be sent.
$_emailPattern protected

string

Regex for email validation
$_from protected

array

The mail which the email is sent from
$_headers protected

array

Associative array of a user defined headers Keys will be prefixed 'X-' as per RFC2822 Section 4.7.5
$_htmlMessage protected

string

Html message
$_message protected

array

Final message to send
$_messageId protected

bool|string

Message ID
$_priority protected

int|null

Contains the optional priority of the email.
$_profile protected

array

A copy of the configuration profile for this instance. This copy can be modified with Email::profile().
$_readReceipt protected

array

The read receipt email
$_replyTo protected

array

The email the recipient will reply to
$_returnPath protected

array
The mail that will be used in case of any errors like
- Remote mailserver down
- Remote user has exceeded his quota
- Unknown user
$_sender protected

array

The sender email
$_subject protected

string

The subject of the email
$_textMessage protected

string

Text message
$_to protected

array

Recipient of the email
$_transferEncodingAvailable protected

array

Available encoding to be set for transfer.
$_transport protected

Cake\Mailer\AbstractTransport|null

The transport instance to use for sending mail.
$_validViewOptions public @property

array
$_viewBuilder protected

Cake\View\ViewBuilder

The view builder instance being used.
$charset public

string

Charset the email body is sent in
$headerCharset public

string|null

Charset the email header is sent in If null, the $charset property will be used as default
$transferEncoding protected

string|null

The email transfer encoding used. If null, the $charset property is used for determined the transfer encoding.
$viewClass public deprecated

string|null

The name of default View class.
$viewVars public deprecated

array

Variables for the view

Method Summary

__clone() public

Clone ViewBuilder instance when email object is cloned.
__construct() public

Constructor
_addEmail() protected

Add email
_applyConfig() protected

Apply the config to an instance
_attachFiles() protected

Attach non-embedded files by adding file contents inside boundaries.
_attachInlineFiles() protected

Attach inline/embedded files to the message.
_checkViewVars() protected

Iterates through hash to clean up and normalize.
_createBoundary() protected

Create unique boundary identifier
_decode() protected

Decode the specified string
_encode() protected

Encode the specified string using the current charset
_encodeString() protected

Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists
_formatAddress() protected

Format addresses
_getContentTransferEncoding() protected

Return the Content-Transfer Encoding value based on the set transferEncoding or set charset.
_getContentTypeCharset() protected

Return charset value for Content-Type.
_getTypes() protected

Gets the text body types that are in this email message
_logDelivery() protected

Log the email message delivery.
_readFile() protected

Read the file contents and return a base64 version of the file contents.
_render() protected

Render the body of the email.
_renderTemplates() protected

Build and set all the view properties needed to render the templated emails. If there is no template set, the $content will be returned in a hash of the text content types for the email.
_setEmail() protected

Set email
_setEmailSingle() protected

Set only 1 email
_validateEmail() protected

Validate email address
_wrap() protected

Wrap the message to follow the RFC 2822 - 2.1.1
addAttachments() public

Add attachments
addBcc() public

Add Bcc
addCc() public

Add Cc
addHeaders() public

Add header for the message
addTo() public

Add To
attachments() public deprecated

Add attachments to the email message
bcc() public deprecated

Bcc
cc() public deprecated

Cc
charset() public deprecated

Charset setter/getter
config() public static deprecated

This method can be used to define configuration adapters for an application or read existing configuration.
configTransport() public static deprecated

Add or read transport configuration.
configured() public static

Returns an array containing the named configurations
configuredTransport() public static deprecated

Returns an array containing the named transport configurations
createFromArray() public

Configures an email instance object from serialized config.
createView() public

Constructs the view class instance based on the current configuration.
deliver() public static

Static method to fast create an instance of \Cake\Mailer\Email
domain() public deprecated

Domain as top level (the part after @)
drop() public static

Drops a constructed adapter.
dropTransport() public static deprecated

Delete transport configuration.
dsnClassMap() public static deprecated

Returns or updates the DSN class map for this class.
emailFormat() public deprecated

Email format
emailPattern() public deprecated

EmailPattern setter/getter
flatten() protected

Converts given value to string
from() public deprecated

From
getAttachments() public

Gets attachments to the email message.
getBcc() public

Gets "bcc" address.
getCc() public

Gets "cc" address.
getCharset() public

Charset getter.
getConfig() public static

Reads existing configuration.
getConfigTransport() public static deprecated

Gets current transport configuration.
getDomain() public

Gets domain.
getDsnClassMap() public static

Returns the DSN class map for this class.
getEmailFormat() public

Gets email format.
getEmailPattern() public

EmailPattern setter/getter
getFrom() public

Gets "from" address.
getHeaderCharset() public

HeaderCharset getter.
getHeaders() public

Get list of headers
getHelpers() public deprecated

Gets helpers to be used when rendering.
getLayout() public deprecated

Gets layout.
getMessageId() public

Gets message ID.
getOriginalSubject() public

Get original subject without encoding
getPriority() public

Gets priority.
getProfile() public

Gets the configuration profile to use for this instance.
getReadReceipt() public

Gets Read Receipt (Disposition-Notification-To header).
getReplyTo() public

Gets "Reply-To" address.
getReturnPath() public

Gets return path.
getSender() public

Gets "sender" address.
getSubject() public

Gets subject.
getTemplate() public

Gets template.
getTheme() public deprecated

Gets theme to use when rendering.
getTo() public

Gets "to" address
getTransferEncoding() public

TransferEncoding getter.
getTransport() public

Gets the transport.
getViewRenderer() public

Gets view class for render.
getViewVars() public

Gets variables to be set on render.
headerCharset() public deprecated

HeaderCharset setter/getter
helpers() public deprecated

Helpers to be used in render
jsonSerialize() public

Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.
message() public

Get generated message (used by transport classes)
messageId() public deprecated

Message-ID
parseDsn() public static

Parses a DSN into a valid connection configuration
profile() public deprecated

Get/Set the configuration profile to use for this instance.
readReceipt() public deprecated

Read Receipt (Disposition-Notification-To header)
replyTo() public deprecated

Reply-To
reset() public

Reset all the internal variables to be able to send out a new email.
returnPath() public deprecated

Return Path
send() public

Send an email using the specified content, template and layout
sender() public deprecated

Sender
serialize() public

Serializes the Email object.
set() public

Saves a variable or an associative array of variables for use inside a template.
setAttachments() public

Add attachments to the email message
setBcc() public

Sets "bcc" address.
setCc() public

Sets "cc" address.
setCharset() public

Charset setter.
setConfig() public static

This method can be used to define configuration adapters for an application.
setConfigTransport() public static deprecated

Sets transport configuration.
setDomain() public

Sets domain.
setDsnClassMap() public static

Updates the DSN class map for this class.
setEmailFormat() public

Sets email format.
setEmailPattern() public

EmailPattern setter/getter
setFrom() public

Sets "from" address.
setHeaderCharset() public

HeaderCharset setter.
setHeaders() public

Sets headers for the message
setHelpers() public deprecated

Sets helpers to be used when rendering.
setLayout() public deprecated

Sets layout.
setMessageId() public

Sets message ID.
setPriority() public

Sets priority.
setProfile() public

Sets the configuration profile to use for this instance.
setReadReceipt() public

Sets Read Receipt (Disposition-Notification-To header).
setReplyTo() public

Sets "Reply-To" address.
setReturnPath() public

Return Path
setSender() public

Sets "sender" address.
setSubject() public

Sets subject.
setTemplate() public

Sets template.
setTheme() public deprecated

Sets theme to use when rendering.
setTo() public

Sets "to" address.
setTransferEncoding() public

TransferEncoding setter.
setTransport() public

Sets the transport.
setViewRenderer() public

Sets view class for render.
setViewVars() public

Sets variables to be set on render.
subject() public deprecated

Get/Set Subject.
template() public deprecated

Template and layout
theme() public deprecated

Theme to use when rendering
to() public deprecated

To
transport() public deprecated

Get/set the transport.
unserialize() public

Unserializes the Email object.
viewBuilder() public

Get the view builder being used.
viewOptions() public deprecated

Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().
viewRender() public deprecated

View class for render
viewVars() public deprecated

Variables to be set on render

Method Detail

__clone() ¶ public

__clone(): void

Clone ViewBuilder instance when email object is cloned.

Returns

void

__construct() ¶ public

__construct(array|string|null $config = null)

Constructor

Parameters

array|string|null $config optional: Array of configs, or string to load configs from app.php

_addEmail() ¶ protected

_addEmail(string $varName, string|array $email, string $name): $this

Add email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name

Returns

$this

Throws

InvalidArgumentException

_applyConfig() ¶ protected

_applyConfig(string|array $config): void

Apply the config to an instance

Parameters

string|array $config: Configuration options.

Returns

void

Throws

InvalidArgumentException
When using a configuration that doesn't exist.

_attachFiles() ¶ protected

_attachFiles(string|null $boundary = null): array

Attach non-embedded files by adding file contents inside boundaries.

Parameters

string|null $boundary optional: Boundary to use. If null, will default to $this->_boundary

Returns

array

_attachInlineFiles() ¶ protected

_attachInlineFiles(string|null $boundary = null): array

Attach inline/embedded files to the message.

Parameters

string|null $boundary optional: Boundary to use. If null, will default to $this->_boundary

Returns

array

_checkViewVars() ¶ protected

_checkViewVars(mixed $item, string $key): void

Iterates through hash to clean up and normalize.

Parameters

mixed $item: Reference to the view var value.
string $key: View var key.

Returns

void

_createBoundary() ¶ protected

_createBoundary(): void

Create unique boundary identifier

Returns

void

_decode() ¶ protected

_decode(string $text): string

Decode the specified string

Parameters

string $text: String to decode

Returns

string

_encode() ¶ protected

_encode(string $text): string

Encode the specified string using the current charset

Parameters

string $text: String to encode

Returns

string

_encodeString() ¶ protected

_encodeString(string $text, string $charset): string

Translates a string for one charset to another if the App.encoding value differs and the mb_convert_encoding function exists

Parameters

string $text: The text to be converted
string $charset: the target encoding

Returns

string

_formatAddress() ¶ protected

_formatAddress(array $address): array

Format addresses

If the address contains non alphanumeric/whitespace characters, it will be quoted as characters like : and , are known to cause issues in address header fields.

Parameters

array $address: Addresses to format.

Returns

array

_getContentTransferEncoding() ¶ protected

_getContentTransferEncoding(): string

Return the Content-Transfer Encoding value based on the set transferEncoding or set charset.

Returns

string

_getContentTypeCharset() ¶ protected

_getContentTypeCharset(): string

Return charset value for Content-Type.

Checks fallback/compatibility types which include workarounds for legacy japanese character sets.

Returns

string

_getTypes() ¶ protected

_getTypes(): array

Gets the text body types that are in this email message

Returns

array

_logDelivery() ¶ protected

_logDelivery(array $contents): void

Log the email message delivery.

Parameters

array $contents: The content with 'headers' and 'message' keys.

Returns

void

_readFile() ¶ protected

_readFile(string $path): string

Read the file contents and return a base64 version of the file contents.

Parameters

string $path: The absolute path to the file to read.

Returns

string

_render() ¶ protected

_render(array $content): array

Render the body of the email.

Parameters

array $content: Content to render

Returns

array

_renderTemplates() ¶ protected

_renderTemplates(string $content): array

Build and set all the view properties needed to render the templated emails. If there is no template set, the $content will be returned in a hash of the text content types for the email.

Parameters

string $content: The content passed in from send() in most cases.

Returns

array

_setEmail() ¶ protected

_setEmail(string $varName, string|array $email, string $name): $this

Set email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name

Returns

$this

Throws

InvalidArgumentException

_setEmailSingle() ¶ protected

_setEmailSingle(string $varName, string|array $email, string $name, string $throwMessage): $this

Set only 1 email

Parameters

string $varName: Property name
string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string $name: Name
string $throwMessage: Exception message

Returns

$this

Throws

InvalidArgumentException

_validateEmail() ¶ protected

_validateEmail(string $email, string $context): void

Validate email address

Parameters

string $email: Email address to validate
string $context: Which property was set

Returns

void

Throws

InvalidArgumentException
If email address does not validate

_wrap() ¶ protected

_wrap(string $message, int $wrapLength = Email::LINE_LENGTH_MUST): array

Wrap the message to follow the RFC 2822 - 2.1.1

Parameters

string $message: Message to wrap
int $wrapLength optional: The line length

Returns

array

addAttachments() ¶ public

addAttachments(string|array $attachments): $this

Add attachments

Parameters

string|array $attachments: String with the filename or array with filenames

Returns

$this

Throws

InvalidArgumentException

addBcc() ¶ public

addBcc(string|array $email, string|null $name = null): $this

Add Bcc

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

addCc() ¶ public

addCc(string|array $email, string|null $name = null): $this

Add Cc

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

addHeaders() ¶ public

addHeaders(array $headers): $this

Add header for the message

Parameters

array $headers: Headers to set.

Returns

$this

addTo() ¶ public

addTo(string|array $email, string|null $name = null): $this

Add To

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

attachments() ¶ public

attachments(string|array|null $attachments = null): array|$this

Add attachments to the email message

Attachments can be defined in a few forms depending on how much control you need:

Attach a single file:

$email->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters

string|array|null $attachments optional: String with the filename or array with filenames

Returns

array|$this

Throws

InvalidArgumentException

bcc() ¶ public

bcc(string|array|null $email = null, string|null $name = null): array|$this

Bcc

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

cc() ¶ public

cc(string|array|null $email = null, string|null $name = null): array|$this

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

charset() ¶ public

charset(string|null $charset = null): string

Charset setter/getter

Parameters

string|null $charset optional: Character set.

Returns

string

config() ¶ public static

config(string|array $key, array|null $config = null): array|null

This method can be used to define configuration adapters for an application or read existing configuration.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Reading config data back:

Cache::config('default');

Setting a cache engine up.

Cache::config('default', $settings);

Injecting a constructed adapter in:

Cache::config('default', $instance);

Configure multiple adapters at once:

Cache::config($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array|null $config optional: An array of name => configuration data for adapter.

Returns

array|null

Throws

BadMethodCallException
When trying to modify an existing config.

configTransport() ¶ public static

configTransport(string|array $key, arrayCake\Mailer\AbstractTransport|null $config = null): array|null

Add or read transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified classname

Parameters

string|array $key: The configuration name to read/write. Or an array of multiple transports to set.
arrayCake\Mailer\AbstractTransport|null $config optional: Either an array of configuration data, or a transport instance.

createFromArray(array $config): $this

Configures an email instance object from serialized config.

Parameters

array $config: Email configuration array.

Returns

$this

createView() ¶ public

createView(string|null $viewClass = null): Cake\View\View

Constructs the view class instance based on the current configuration.

Parameters

string|null $viewClass optional: Optional namespaced class name of the View class to instantiate.

Returns

Cake\View\View

Throws

Cake\View\Exception\MissingViewException
If view class was not found.

deliver() ¶ public static

deliver(string|array|null $to = null, string|null $subject = null, string|array|null $message = null, string|array $config = 'default', bool $send = true): static

Static method to fast create an instance of \Cake\Mailer\Email

Parameters

string|array|null $to optional: Address to send (see Cake\Mailer\Email::to()). If null, will try to use 'to' from transport config
string|null $subject optional: String of subject or null to use 'subject' from transport config
string|array|null $message optional: String with message or array with variables to be used in render
string|array $config optional: String to use Email delivery profile from app.php or array with configs
bool $send optional: Send the email or just return the instance pre-configured

Returns

static

Throws

InvalidArgumentException

domain() ¶ public

domain(string|null $domain = null): string|$this

Domain as top level (the part after @)

Parameters

string|null $domain optional: Manually set the domain for CLI mailing

Returns

string|$this

drop() ¶ public static

drop(string $config): bool

Drops a constructed adapter.

If you wish to modify an existing configuration, you should drop it, change configuration and then re-add it.

If the implementing objects supports a $_registry object the named configuration will also be unloaded from the registry.

Parameters

string $config: An existing configuration you wish to remove.

Returns

bool

dropTransport() ¶ public static

dropTransport(string $key): void

Delete transport configuration.

Parameters

string $key: The transport name to remove.

Returns

void

dsnClassMap() ¶ public static

dsnClassMap(array|null $map = null): array

Returns or updates the DSN class map for this class.

Parameters

array|null $map optional: Additions/edits to the class map to apply.

Returns

array

emailFormat() ¶ public

emailFormat(string|null $format = null): string|$this

Email format

Parameters

string|null $format optional: Formatting string.

Returns

string|$this

Throws

InvalidArgumentException

emailPattern() ¶ public

emailPattern(string|bool|null $regex = false): string|$this

EmailPattern setter/getter

Parameters

string|bool|null $regex optional: The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead, false or nothing to return the current value

Returns

string|$this

flatten() ¶ protected

flatten(string|array $value): string

Converts given value to string

Parameters

string|array $value: The value to convert

Returns

string

from() ¶ public

from(string|array|null $email = null, string|null $name = null): array|$this

From

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

getConfig(string $key): array|null

Reads existing configuration.

Parameters

string $key: The name of the configuration.

Returns

array|null

getConfigTransport() ¶ public static

getConfigTransport(string $key): array|null

Gets current transport configuration.

Parameters

string $key: The configuration name to read.

Returns

array|null

getDomain() ¶ public

getDomain(): string

Gets domain.

Returns

string

getDsnClassMap() ¶ public static

getDsnClassMap(): array

Returns the DSN class map for this class.

Returns

array

getEmailFormat() ¶ public

getEmailFormat(): string

Gets email format.

Returns

string

getEmailPattern() ¶ public

getEmailPattern(): string

EmailPattern setter/getter

Returns

string

getFrom() ¶ public

getFrom(): array

Gets "from" address.

Returns

array

getHeaderCharset() ¶ public

getHeaderCharset(): string

HeaderCharset getter.

Returns

string

getHeaders() ¶ public

getHeaders(array $include = []): array

Get list of headers

Includes:

from
replyTo
readReceipt
returnPath
to
cc
bcc
subject

Parameters

array $include optional: List of headers.

Returns

array

getHelpers() ¶ public

getHelpers(): array

Gets helpers to be used when rendering.

Returns

array

getLayout() ¶ public

getLayout(): string

Gets layout.

Returns

string

getMessageId() ¶ public

getMessageId(): bool|string

Gets message ID.

Returns

bool|string

getOriginalSubject() ¶ public

getOriginalSubject(): string

Get original subject without encoding

Returns

string

getPriority() ¶ public

getPriority(): int

Gets priority.

Returns

int

getProfile() ¶ public

getProfile(): string|array

Gets the configuration profile to use for this instance.

Returns

string|array

getReadReceipt() ¶ public

getReadReceipt(): array

Gets Read Receipt (Disposition-Notification-To header).

Returns

array

getReplyTo() ¶ public

getReplyTo(): array

Gets "Reply-To" address.

Returns

array

getReturnPath() ¶ public

getReturnPath(): array

Gets return path.

Returns

array

getSender() ¶ public

getSender(): array

Gets "sender" address.

Returns

array

getSubject() ¶ public

getSubject(): string

Gets subject.

Returns

string

getTemplate() ¶ public

getTemplate(): string

Gets template.

Returns

string

getTheme() ¶ public

getTheme(): string

Gets theme to use when rendering.

Returns

string

getTo() ¶ public

getTo(): array

Gets "to" address

Returns

array

getTransferEncoding() ¶ public

getTransferEncoding(): string|null

TransferEncoding getter.

Returns

string|null

getTransport() ¶ public

getTransport(): Cake\Mailer\AbstractTransport

Gets the transport.

Returns

Cake\Mailer\AbstractTransport

getViewRenderer() ¶ public

getViewRenderer(): string

Gets view class for render.

Returns

string

getViewVars() ¶ public

getViewVars(): array

Gets variables to be set on render.

Returns

array

headerCharset() ¶ public

headerCharset(string|null $charset = null): string

HeaderCharset setter/getter

Parameters

string|null $charset optional: Character set.

Returns

string

helpers() ¶ public

helpers(array|null $helpers = null): array|$this

Helpers to be used in render

Parameters

array|null $helpers optional: Helpers list.

Returns

array|$this

jsonSerialize() ¶ public

jsonSerialize(): array

Serializes the email object to a value that can be natively serialized and re-used to clone this email instance.

It has certain limitations for viewVars that are good to know:

ORM\Query executed and stored as resultset
- SimpleXMLElements stored as associative array
- Exceptions stored as strings
- Resources, \Closure and \PDO are not supported.

Returns

array

Throws

Exception
When a view var object can not be properly serialized.

message() ¶ public

message(string|null $type = null): string|array

Get generated message (used by transport classes)

Parameters

string|null $type optional: Use MESSAGE_* constants or null to return the full message as array

Returns

string|array

messageId() ¶ public

messageId(bool|string|null $message = null): bool|string|$this

Message-ID

Parameters

bool|string|null $message optional: True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID

Returns

bool|string|$this

Throws

InvalidArgumentException

parseDsn() ¶ public static

parseDsn(string $dsn): array

Parses a DSN into a valid connection configuration

This method allows setting a DSN using formatting similar to that used by PEAR::DB. The following is an example of its usage:

$dsn = 'mysql://user:pass@localhost/database?';
$config = ConnectionManager::parseDsn($dsn);

$dsn = 'Cake\Log\Engine\FileLog://?types=notice,info,debug&file=debug&path=LOGS';
$config = Log::parseDsn($dsn);

$dsn = 'smtp://user:secret@localhost:25?timeout=30&client=null&tls=null';
$config = Email::parseDsn($dsn);

$dsn = 'file:///?className=\My\Cache\Engine\FileEngine';
$config = Cache::parseDsn($dsn);

$dsn = 'File://?prefix=myapp_cake_core_&serialize=true&duration=+2 minutes&path=/tmp/persistent/';
$config = Cache::parseDsn($dsn);

For all classes, the value of scheme is set as the value of both the className unless they have been otherwise specified.

Note that querystring arguments are also parsed and set as values in the returned configuration.

Parameters

string $dsn: The DSN string to convert to a configuration array

Returns

array

Throws

InvalidArgumentException
If not passed a string, or passed an invalid string

profile() ¶ public

profile(null|string|array $config = null): string|array|$this

Get/Set the configuration profile to use for this instance.

Parameters

null|string|array $config optional: String with configuration name, or an array with config or null to return current config.

Returns

string|array|$this

readReceipt() ¶ public

readReceipt(string|array|null $email = null, string|null $name = null): array|$this

Read Receipt (Disposition-Notification-To header)

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

replyTo() ¶ public

replyTo(string|array|null $email = null, string|null $name = null): array|$this

Reply-To

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

reset() ¶ public

reset(): $this

Reset all the internal variables to be able to send out a new email.

Returns

$this

returnPath() ¶ public

returnPath(string|array|null $email = null, string|null $name = null): array|$this

Return Path

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

send() ¶ public

send(string|array|null $content = null): array

Send an email using the specified content, template and layout

Parameters

string|array|null $content optional: String with message or array with messages

Returns

array

Throws

BadMethodCallException

sender() ¶ public

sender(string|array|null $email = null, string|null $name = null): array|$this

Sender

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

Throws

InvalidArgumentException

serialize() ¶ public

serialize(): string

Serializes the Email object.

Returns

string

set() ¶ public

set(string|array $name, mixed $value = null): $this

Saves a variable or an associative array of variables for use inside a template.

Parameters

string|array $name: A string or an array of data.
mixed $value optional: Value in case $name is a string (which then works as the key). Unused if $name is an associative array, otherwise serves as the values to $name's keys.

Returns

$this

setAttachments() ¶ public

setAttachments(string|array $attachments): $this

Add attachments to the email message

Attachments can be defined in a few forms depending on how much control you need:

Attach a single file:

$email->setAttachments('path/to/file');

Attach a file with a different filename:

$email->setAttachments(['custom_name.txt' => 'path/to/file.txt']);

Attach a file and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'file' => 'path/to/file',
     'mimetype' => 'image/png',
     'contentId' => 'abc123',
     'contentDisposition' => false
   ]
]);

Attach a file from string and specify additional properties:

$email->setAttachments(['custom_name.png' => [
     'data' => file_get_contents('path/to/file'),
     'mimetype' => 'image/png'
   ]
]);

The contentId key allows you to specify an inline attachment. In your email text, you can use <img src="cid:abc123" /> to display the image inline.

The contentDisposition key allows you to disable the Content-Disposition header, this can improve attachment compatibility with outlook email clients.

Parameters

string|array $attachments: String with the filename or array with filenames

Returns

$this

Throws

InvalidArgumentException

setBcc() ¶ public

setBcc(string|array $email, string|null $name = null): $this

Sets "bcc" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setCc() ¶ public

setCc(string|array $email, string|null $name = null): $this

Sets "cc" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setCharset() ¶ public

setCharset(string|null $charset): $this

Charset setter.

Parameters

string|null $charset: Character set.

Returns

$this

setConfig() ¶ public static

setConfig(string|array $key, array $config = null): void

This method can be used to define configuration adapters for an application.

To change an adapter's configuration at runtime, first drop the adapter and then reconfigure it.

Adapters will not be constructed until the first operation is done.

Usage

Assuming that the class' name is Cache the following scenarios are supported:

Setting a cache engine up.

Cache::setConfig('default', $settings);

Injecting a constructed adapter in:

Cache::setConfig('default', $instance);

Configure multiple adapters at once:

Cache::setConfig($arrayOfConfig);

Parameters

string|array $key: The name of the configuration, or an array of multiple configs.
array $config optional: An array of name => configuration data for adapter.

Returns

void

Throws

BadMethodCallException
When trying to modify an existing config.
LogicException
When trying to store an invalid structured config array.

setConfigTransport() ¶ public static

setConfigTransport(string|array $key, arrayCake\Mailer\AbstractTransport|null $config = null): void

Sets transport configuration.

Use this method to define transports to use in delivery profiles. Once defined you cannot edit the configurations, and must use Email::dropTransport() to flush the configuration first.

When using an array of configuration data a new transport will be constructed for each message sent. When using a Closure, the closure will be evaluated for each message.

The className is used to define the class to use for a transport. It can either be a short name, or a fully qualified class name

Parameters

string|array $key: The configuration name to write. Or an array of multiple transports to set.
arrayCake\Mailer\AbstractTransport|null $config optional: Either an array of configuration data, or a transport instance. Null when using key as array.

Returns

void

setDomain() ¶ public

setDomain(string $domain): $this

Sets domain.

Domain as top level (the part after @).

Parameters

string $domain: Manually set the domain for CLI mailing.

Returns

$this

setDsnClassMap() ¶ public static

setDsnClassMap(array $map): void

Updates the DSN class map for this class.

Parameters

array $map: Additions/edits to the class map to apply.

Returns

void

setEmailFormat() ¶ public

setEmailFormat(string $format): $this

Sets email format.

Parameters

string $format: Formatting string.

Returns

$this

Throws

InvalidArgumentException

setEmailPattern() ¶ public

setEmailPattern(string|null $regex): $this

EmailPattern setter/getter

Parameters

string|null $regex: The pattern to use for email address validation, null to unset the pattern and make use of filter_var() instead.

Returns

$this

setFrom() ¶ public

setFrom(string|array $email, string|null $name = null): $this

Sets "from" address.

Parameters

string|array $email: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setHeaderCharset() ¶ public

setHeaderCharset(string|null $charset): $this

HeaderCharset setter.

Parameters

string|null $charset: Character set.

Returns

$this

setHeaders() ¶ public

setHeaders(array $headers): $this

Sets headers for the message

Parameters

array $headers: Associative array containing headers to be set.

Returns

$this

setHelpers() ¶ public

setHelpers(array $helpers): $this

Sets helpers to be used when rendering.

Parameters

array $helpers: Helpers list.

Returns

$this

setLayout() ¶ public

setLayout(string|null $layout): $this

Sets layout.

Parameters

string|null $layout: Layout name or null to not use

Returns

$this

setMessageId() ¶ public

setMessageId(bool|string $message): $this

Sets message ID.

Parameters

bool|string $message: True to generate a new Message-ID, False to ignore (not send in email), String to set as Message-ID.

Returns

$this

Throws

InvalidArgumentException

setPriority() ¶ public

setPriority(int|null $priority): $this

Sets priority.

Parameters

int|null $priority: 1 (highest) to 5 (lowest)

Returns

$this

setProfile() ¶ public

setProfile(string|array $config): $this

Sets the configuration profile to use for this instance.

Parameters

string|array $config: String with configuration name, or an array with config.

Returns

$this

setReadReceipt() ¶ public

setReadReceipt(string|array $email, string|null $name = null): $this

Sets Read Receipt (Disposition-Notification-To header).

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setReplyTo() ¶ public

setReplyTo(string|array $email, string|null $name = null): $this

Sets "Reply-To" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setReturnPath() ¶ public

setReturnPath(string|array $email, string|null $name = null): $this

Return Path

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setSender() ¶ public

setSender(string|array $email, string|null $name = null): $this

Sets "sender" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

Throws

InvalidArgumentException

setSubject() ¶ public

setSubject(string $subject): $this

Sets subject.

Parameters

string $subject: Subject string.

Returns

$this

setTemplate() ¶ public

setTemplate(string|null $template): $this

Sets template.

Parameters

string|null $template: Template name or null to not use.

Returns

$this

setTheme() ¶ public

setTheme(string $theme): $this

Sets theme to use when rendering.

Parameters

string $theme: Theme name.

Returns

$this

setTo() ¶ public

setTo(string|array $email, string|null $name = null): $this

Sets "to" address.

Parameters

string|array $email: String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

$this

setTransferEncoding() ¶ public

setTransferEncoding(string|null $encoding): $this

TransferEncoding setter.

Parameters

string|null $encoding: Encoding set.

Returns

$this

setTransport() ¶ public

setTransport(stringCake\Mailer\AbstractTransport $name): $this

Sets the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters

stringCake\Mailer\AbstractTransport $name: Either the name of a configured transport, or a transport instance.

Returns

$this

Throws

LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

setViewRenderer() ¶ public

setViewRenderer(string $viewClass): $this

Sets view class for render.

Parameters

string $viewClass: View class name.

Returns

$this

setViewVars() ¶ public

setViewVars(array $viewVars): $this

Sets variables to be set on render.

Parameters

array $viewVars: Variables to set for view.

Returns

$this

subject() ¶ public

subject(string|null $subject = null): string|$this

Get/Set Subject.

Parameters

string|null $subject optional: Subject string.

Returns

string|$this

template() ¶ public

template(bool|string $template = false, bool|string $layout = false): array|$this

Template and layout

Parameters

bool|string $template optional: Template name or null to not use
bool|string $layout optional: Layout name or null to not use

Returns

array|$this

theme() ¶ public

theme(string|null $theme = null): string|$this

Theme to use when rendering

Parameters

string|null $theme optional: Theme name.

Returns

string|$this

to() ¶ public

to(string|array|null $email = null, string|null $name = null): array|$this

Parameters

string|array|null $email optional: Null to get, String with email, Array with email as key, name as value or email as value (without name)
string|null $name optional: Name

Returns

array|$this

transport() ¶ public

transport(stringCake\Mailer\AbstractTransport|null $name = null): Cake\Mailer\AbstractTransport|$this

Get/set the transport.

When setting the transport you can either use the name of a configured transport or supply a constructed transport.

Parameters

stringCake\Mailer\AbstractTransport|null $name optional: Either the name of a configured transport, or a transport instance.

Returns

Cake\Mailer\AbstractTransport|$this

Throws

LogicException
When the chosen transport lacks a send method.
InvalidArgumentException
When $name is neither a string nor an object.

unserialize() ¶ public

unserialize(string $data): static

Unserializes the Email object.

Parameters

string $data: Serialized string.

Returns

static

viewBuilder() ¶ public

viewBuilder(): Cake\View\ViewBuilder

Get the view builder being used.

Returns

Cake\View\ViewBuilder

viewOptions() ¶ public

viewOptions(string|array|null $options = null, bool $merge = true): array

Get/Set valid view options in the object's _validViewOptions property. The property is created as an empty array if it is not set. If called without any parameters it will return the current list of valid view options. See createView().

Parameters

string|array|null $options optional: string or array of string to be appended to _validViewOptions.
bool $merge optional: Whether to merge with or override existing valid View options. Defaults to true.

Returns

array

viewRender() ¶ public

viewRender(string|null $viewClass = null): string|$this

View class for render

Parameters

string|null $viewClass optional: View class name.

Returns

string|$this

viewVars() ¶ public

viewVars(array|null $viewVars = null): array|$this

Variables to be set on render

Parameters

array|null $viewVars optional: Variables to set for view.

Returns

array|$this

Property Detail

`$_appCharset` ¶ protected

The application wide charset, used to encode headers and body

Type

string|null

`$_attachments` ¶ protected

List of files that should be attached to the email.

Only absolute paths

Type

array

`$_bcc` ¶ protected

Blind Carbon Copy

List of email's that should receive a copy of the email. The Recipient WILL NOT be able to see this list

Type

array

`$_boundary` ¶ protected

If set, boundary to use for multipart mime messages

Type

string|null

`$_cc` ¶ protected

Type

array

`$_emailPattern` ¶ protected

Remote mailserver down
Remote user has exceeded his quota
Unknown user

array

Namespaces

Class Email

Configuration

Constants

Property Summary

Method Summary

__clone() public

__construct() public

_addEmail() protected

_applyConfig() protected

_attachFiles() protected

_attachInlineFiles() protected

_checkViewVars() protected

_createBoundary() protected

_decode() protected

_encode() protected

_encodeString() protected

_formatAddress() protected

_getContentTransferEncoding() protected

_getContentTypeCharset() protected

_getTypes() protected

_logDelivery() protected

_readFile() protected

_render() protected

_renderTemplates() protected

_setEmail() protected

_setEmailSingle() protected

_validateEmail() protected

_wrap() protected

addAttachments() public

addBcc() public

addCc() public

addHeaders() public

addTo() public

attachments() public deprecated

bcc() public deprecated

cc() public deprecated

charset() public deprecated

config() public static deprecated

configTransport() public static deprecated

configured() public static

configuredTransport() public static deprecated

createFromArray() public

createView() public

deliver() public static

domain() public deprecated

drop() public static

dropTransport() public static deprecated

dsnClassMap() public static deprecated

emailFormat() public deprecated

emailPattern() public deprecated

flatten() protected

from() public deprecated

getAttachments() public

getBcc() public

getCc() public

getCharset() public

getConfig() public static

getConfigTransport() public static deprecated

getDomain() public

getDsnClassMap() public static

getEmailFormat() public

getEmailPattern() public

getFrom() public

getHeaderCharset() public

getHeaders() public

getHelpers() public deprecated

getLayout() public deprecated

getMessageId() public

getOriginalSubject() public

getPriority() public

getProfile() public

getReadReceipt() public

getReplyTo() public

getReturnPath() public

getSender() public

getSubject() public

getTemplate() public

getTheme() public deprecated

getTo() public