Class Message

Email message class.

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

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_BOTH ¶
```
'both'
```
Type of message - BOTH
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
$charset protected

string

Charset the email body is sent in
$charset8bit protected

array

8Bit character 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
$emailFormat protected

string

What format should the email be sent in
$emailFormatAvailable protected

array

Available formats to be sent.
$emailPattern protected

string|null

Regex for email validation
$from protected

array

The mail which the email is sent from
$headerCharset protected

string|null

Charset the email header is sent in If null, the $charset property will be used as default
$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.
$readReceipt protected

array

The read receipt email
$replyTo protected

array

List of email(s) that 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
$transferEncoding protected

string|null

The email transfer encoding used. If null, the $charset property is used for determined the transfer encoding.
$transferEncodingAvailable protected

array

Available encoding to be set for transfer.

Method Summary

__construct() public

Constructor
addAttachments() public

Add attachments
addBcc() public

Add "bcc" address.
addCc() public

Add "cc" address.
addEmail() protected

Add email
addHeaders() public

Add header for the message
addReplyTo() public

Add "Reply-To" address.
addTo() public

Add "To" address.
attachFiles() protected

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

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

Create unique boundary identifier
createFromArray() public

Configures an email instance object from serialized config.
decodeForHeader() protected

Decode the specified string
encodeForHeader() 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
generateMessage() protected

Generate full message.
getAttachments() public

Gets attachments to the email message.
getBcc() public

Gets "bcc" address.
getBody() public

Get generated message body as array.
getBodyHtml() public

Get HTML body of message.
getBodyString() public

Get generated body as string.
getBodyText() public

Get text body of message.
getBodyTypes() public

Gets the body types that are in this email message
getCc() public

Gets "cc" address.
getCharset() public

Charset getter.
getContentTransferEncoding() public

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

Return charset value for Content-Type.
getDomain() public

Gets domain.
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
getHeadersString() public

Get headers as string.
getMessageId() public

Gets message ID.
getOriginalSubject() public

Get original subject without encoding
getPriority() public

Gets priority.
getReadReceipt() public

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

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

Gets return path.
getSender() public

Gets the "sender" address. See RFC link below for full explanation.
getSubject() public

Gets subject.
getTo() public

Gets "to" address
getTransferEncoding() public

TransferEncoding getter.
jsonSerialize() public

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

Read the file contents and return a base64 version of the file contents.
reset() public

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

Serializes the Email object.
setAttachments() public

Add attachments to the email message
setBcc() public

Sets "bcc" address.
setBody() public

Set message body.
setBodyHtml() public

Set HTML body for message.
setBodyText() public

Set text body for message.
setCc() public

Sets "cc" address.
setCharset() public

Charset setter.
setConfig() public

Sets the configuration for this instance.
setDomain() public

Sets domain.
setEmail() protected

Set email
setEmailFormat() public

Sets email format.
setEmailPattern() public

EmailPattern setter/getter
setEmailSingle() protected

Set only 1 email
setFrom() public

Sets "from" address.
setHeaderCharset() public

HeaderCharset setter.
setHeaders() public

Sets headers for the message
setMessageId() public

Sets message ID.
setPriority() public

Sets priority.
setReadReceipt() public

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

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

Sets return path.
setSender() public

Sets the "sender" address. See RFC link below for full explanation.
setSubject() public

Sets subject.
setTo() public

Sets "to" address.
setTransferEncoding() public

TransferEncoding setter.
unserialize() public

Unserializes the Message object.
validateEmail() protected

Validate email address
wrap() protected

Wrap the message to follow the RFC 2822 - 2.1.1

Method Detail

__construct() ¶ public

__construct(array|null $config = null)

Constructor

Parameters

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

addAttachments() ¶ public

addAttachments(array $attachments): $this

Add attachments

Parameters

array $attachments: Array of filenames.

Returns

$this

Throws

InvalidArgumentException

addBcc() ¶ public

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

Add "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

addCc() ¶ public

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

Add "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

addEmail() ¶ protected

addEmail(string $varName, string|array $email, string|null $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|null $name: Name

Returns

$this

Throws

InvalidArgumentException

addHeaders() ¶ public

addHeaders(array $headers): $this

Add header for the message

Parameters

array $headers: Headers to set.

Returns

$this

addReplyTo() ¶ public

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

Add "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

addTo() ¶ public

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

Add "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

attachFiles() ¶ protected

attachFiles(string|null $boundary = null): string[]

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

string[]

attachInlineFiles() ¶ protected

attachInlineFiles(string|null $boundary = null): string[]

Attach inline/embedded files to the message.

Parameters

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

Returns

string[]

createBoundary() ¶ protected

createBoundary(): void

Create unique boundary identifier

Returns

void

createFromArray() ¶ public

createFromArray(array $config): $this

Configures an email instance object from serialized config.

Parameters

array $config: Email configuration array.

Returns

$this

decodeForHeader() ¶ protected

decodeForHeader(string $text): string

Decode the specified string

Parameters

string $text: String to decode

Returns

string

encodeForHeader() ¶ protected

encodeForHeader(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

generateMessage() ¶ protected

generateMessage(): string[]

Generate full message.

Returns

string[]

getAttachments() ¶ public

getAttachments(): array

Gets attachments to the email message.

Returns

array

getBcc() ¶ public

getBcc(): array

Gets "bcc" address.

Returns

array

getBody() ¶ public

getBody(): array

Get generated message body as array.

Returns

array

getBodyHtml() ¶ public

getBodyHtml(): string

Get HTML body of message.

Returns

string

getBodyString() ¶ public

getBodyString(string $eol = "\r\n"): string

Get generated body as string.

Parameters

string $eol optional: End of line string for imploding.

Returns

string

getBodyText() ¶ public

getBodyText(): string

Get text body of message.

Returns

string

getBodyTypes() ¶ public

getBodyTypes(): array

Gets the body types that are in this email message

Returns

array

getCc() ¶ public

getCc(): array

Gets "cc" address.

Returns

array

getCharset() ¶ public

getCharset(): string

Charset getter.

Returns

string

getContentTransferEncoding() ¶ public

getContentTransferEncoding(): string

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

Returns

string

getContentTypeCharset() ¶ public

getContentTypeCharset(): string

Return charset value for Content-Type.

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

Returns

string

getDomain() ¶ public

getDomain(): string

Gets domain.

Returns

string

getEmailFormat() ¶ public

getEmailFormat(): string

Gets email format.

Returns

string

getEmailPattern() ¶ public

getEmailPattern(): string|null

EmailPattern setter/getter

Returns

string|null

getFrom() ¶ public

getFrom(): array

Gets "from" address.

Returns

array

getHeaderCharset() ¶ public

getHeaderCharset(): string

HeaderCharset getter.

Returns

string

getHeaders() ¶ public

getHeaders(string[] $include = []): string[]

Get list of headers

Includes:

from
replyTo
readReceipt
returnPath
to
cc
bcc
subject

Parameters

string[] $include optional: List of headers.

Returns

string[]

getHeadersString() ¶ public

getHeadersString(string[] $include = [], string $eol = "\r\n", Closure $callback = null): string

Get headers as string.

Parameters

string[] $include optional: List of headers.
string $eol optional: End of line string for concatenating headers.
Closure $callback optional: Callback to run each header value through before stringifying.

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

Gets priority.

Returns

int|null

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 the "sender" address. See RFC link below for full explanation.

Returns

array

Links

https://tools.ietf.org/html/rfc2822.html#section-3.6.2

getSubject() ¶ public

getSubject(): string

Gets subject.

Returns

string

getTo() ¶ public

getTo(): array

Gets "to" address

Returns

array

getTransferEncoding() ¶ public

getTransferEncoding(): string|null

TransferEncoding getter.

Returns

string|null

jsonSerialize() ¶ public

jsonSerialize(): array

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

Returns

array

Throws

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

readFile() ¶ protected

readFile(stringPsr\Http\Message\UploadedFileInterface $file): string

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

Parameters

stringPsr\Http\Message\UploadedFileInterface $file: The absolute path to the file to read or UploadedFileInterface instance.

Returns

string

reset() ¶ public

reset(): $this

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

Returns

$this

serialize() ¶ public

serialize(): string

Serializes the Email object.

Returns

string

setAttachments() ¶ public

setAttachments(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:

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

Attach a file with a different filename:

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

Attach a file and specify additional properties:

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

Attach a file from string and specify additional properties:

$this->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

array $attachments: Array of 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

setBody() ¶ public

setBody(array $content): $this

Set message body.

Parameters

array $content: Content array with keys "text" and/or "html" with content string of respective type.

Returns

$this

setBodyHtml() ¶ public

setBodyHtml(string $content): $this

Set HTML body for message.

Parameters

string $content: Content string

Returns

$this

setBodyText() ¶ public

setBodyText(string $content): $this

Set text body for message.

Parameters

string $content: Content string

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 $charset): $this

Charset setter.

Parameters

string $charset: Character set.

Returns

$this

setConfig() ¶ public

setConfig(array $config): $this

Sets the configuration for this instance.

Parameters

array $config: Config array.

Returns

$this

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

setEmail() ¶ protected

setEmail(string $varName, string|array $email, string|null $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|null $name: Name

Returns

$this

Throws

InvalidArgumentException

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

setEmailSingle() ¶ protected

setEmailSingle(string $varName, string|array $email, string|null $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|null $name: Name
string $throwMessage: Exception message

Returns

$this

Throws

InvalidArgumentException

setFrom() ¶ public

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

Sets "from" 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

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

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

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

Sets 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 the "sender" address. See RFC link below for full explanation.

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

Links

https://tools.ietf.org/html/rfc2822.html#section-3.6.2

setSubject() ¶ public

setSubject(string $subject): $this

Sets subject.

Parameters

string $subject: Subject string.

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

Throws

InvalidArgumentException

unserialize() ¶ public

unserialize(string $data): void

Unserializes the Message object.

Parameters

string $data: Serialized string.

Returns

void

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|null $message = null, int $wrapLength = self::LINE_LENGTH_MUST): array

Wrap the message to follow the RFC 2822 - 2.1.1

Parameters

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

Returns

array

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

Carbon Copy

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

Type

array

`$charset` ¶ protected

Charset the email body is sent in

Type

string

`$charset8bit` ¶ protected

8Bit character sets

Type

array

`$contentTypeCharset` ¶ protected

Define Content-Type charset name

Type

array

`$domain` ¶ protected

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

Type

string

`$emailFormat` ¶ protected

What format should the email be sent in

Type

string

`$emailFormatAvailable` ¶ protected

Available formats to be sent.

Type

array

`$emailPattern` ¶ protected

Regex for email validation

If null, filter_var() will be used. Use the emailPattern() method to set a custom pattern.'

Type

string|null

`$from` ¶ protected

The mail which the email is sent from

Type

array

`$headerCharset` ¶ protected

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

Type

string|null

`$headers` ¶ protected

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

Type

array

`$htmlMessage` ¶ protected

Html message

Type

string

`$message` ¶ protected

Final message to send

Type

array

`$messageId` ¶ protected

Message ID

Type

bool|string

`$priority` ¶ protected

Contains the optional priority of the email.

Type

int|null

`$readReceipt` ¶ protected

The read receipt email

Type

array

`$replyTo` ¶ protected

List of email(s) that the recipient will reply to

Type

array

`$returnPath` ¶ protected

The mail that will be used in case of any errors like

Remote mailserver down
Remote user has exceeded his quota
Unknown user

Type

array

`$sender` ¶ protected

The sender email

Type

array

`$subject` ¶ protected

The subject of the email

Type

string

`$textMessage` ¶ protected

Text message

Type

string

`$to` ¶ protected

Recipient of the email

Type

array

`$transferEncoding` ¶ protected

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

Type

string|null

`$transferEncodingAvailable` ¶ protected

Available encoding to be set for transfer.

Type

array

Namespaces

Class Message

Constants

Property Summary

Method Summary

__construct() public

addAttachments() public

addBcc() public

addCc() public

addEmail() protected

addHeaders() public

addReplyTo() public

addTo() public

attachFiles() protected

attachInlineFiles() protected

createBoundary() protected

createFromArray() public

decodeForHeader() protected

encodeForHeader() protected

encodeString() protected

formatAddress() protected

generateMessage() protected

getAttachments() public

getBcc() public

getBody() public

getBodyHtml() public

getBodyString() public

getBodyText() public

getBodyTypes() public

getCc() public

getCharset() public

getContentTransferEncoding() public

getContentTypeCharset() public

getDomain() public

getEmailFormat() public

getEmailPattern() public

getFrom() public

getHeaderCharset() public

getHeaders() public

getHeadersString() public

getMessageId() public

getOriginalSubject() public

getPriority() public

getReadReceipt() public

getReplyTo() public

getReturnPath() public

getSender() public

getSubject() public

getTo() public

getTransferEncoding() public

jsonSerialize() public

readFile() protected

reset() public

serialize() public

setAttachments() public

setBcc() public

setBody() public

setBodyHtml() public

setBodyText() public

setCc() public

setCharset() public

setConfig() public

setDomain() public

setEmail() protected

setEmailFormat() public

setEmailPattern() public

setEmailSingle() protected

setFrom() public

setHeaderCharset() public

setHeaders() public

setMessageId() public

setPriority() public

setReadReceipt() public

setReplyTo() public

setReturnPath() public

setSender() public

setSubject() public

setTo() public

setTransferEncoding() public

unserialize() public