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 summary

  • string
    EMAIL_PATTERN
    '/^((?:[\\p{L}0-9.!#$%&\'*+\\/=?^_`{|}~-]+)*@[\\p{L}0-9-._]+)$/ui'
  • int
    LINE_LENGTH_MUST
    998
  • int
    LINE_LENGTH_SHOULD
    78
  • string
    MESSAGE_BOTH
    'both'
  • string
    MESSAGE_HTML
    'html'
  • string
    MESSAGE_TEXT
    'text'

Properties 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

  • array

    Define Content-Type charset name

  • $domain protected
    string

    Domain for messageId generation.

  • $emailFormat protected
    string

    What format should the email be sent in

  • 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

    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

  • $transferEncoding protected
    string|null

    The email transfer encoding used.

  • array

    Available encoding to be set for transfer.

Method Summary

Method Detail

__construct() public

__construct(?array $config)

Constructor

Parameters

array|null $config optional

Array of configs, or string to load configs from app.php

addAttachments() public

addAttachments(array $attachments)

Add attachments

Parameters

array $attachments

Array of filenames.

Returns

$this

Throws

InvalidArgumentException

See Also

\Cake\Mailer\Email::setAttachments()

addBcc() public

addBcc(mixed $email, ?string $name)

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

addCc() public

addCc(mixed $email, ?string $name)

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

addEmail() protected

addEmail(string $varName, mixed $email, ?string $name)

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)

Add header for the message

Parameters

array $headers

Headers to set.

Returns

$this

addTo() public

addTo(mixed $email, ?string $name)

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

attachFiles() protected

attachFiles(?string $boundary)

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[]

An array of lines to add to the message

attachInlineFiles() protected

attachInlineFiles(?string $boundary)

Attach inline/embedded files to the message.

Parameters

string|null $boundary optional

Boundary to use. If null, will default to $this->boundary

Returns

string[]

An array of lines to add to the message

createBoundary() protected

createBoundary()

Create unique boundary identifier

createFromArray() public

createFromArray(array $config)

Configures an email instance object from serialized config.

Parameters

array $config

Email configuration array.

Returns

$this

Configured email instance.

decodeForHeader() protected

decodeForHeader(string $text)

Decode the specified string

Parameters

string $text

String to decode

Returns

string

Decoded string

encodeForHeader() protected

encodeForHeader(string $text)

Encode the specified string using the current charset

Parameters

string $text

String to encode

Returns

string

Encoded string

encodeString() protected

encodeString(string $text, string $charset)

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)

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

Generate full message.

Returns

string[]

getAttachments() public

getAttachments()

Gets attachments to the email message.

Returns

array

Array of attachments.

getBcc() public

getBcc()

Gets "bcc" address.

Returns

array

getBody() public

getBody()

Get generated message body as array.

Returns

array

getBodyHtml() public

getBodyHtml()

Get HTML body of message.

Returns

string

getBodyString() public

getBodyString(string $eol)

Get generated body as string.

Parameters

string $eol optional

End of line string for imploding.

Returns

string

See Also

\Cake\Mailer\Message::getBody()

getBodyText() public

getBodyText()

Get text body of message.

Returns

string

getBodyTypes() public

getBodyTypes()

Gets the body types that are in this email message

Returns

array

Array of types. Valid types are Email::MESSAGE_TEXT and Email::MESSAGE_HTML

getCc() public

getCc()

Gets "cc" address.

Returns

array

getCharset() public

getCharset()

Charset getter.

Returns

string

Charset

getContentTransferEncoding() public

getContentTransferEncoding()

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

Returns

string

getContentTypeCharset() public

getContentTypeCharset()

Return charset value for Content-Type.

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

Returns

string

getDomain() public

getDomain()

Gets domain.

Returns

string

getEmailFormat() public

getEmailFormat()

Gets email format.

Returns

string

getEmailPattern() public

getEmailPattern()

EmailPattern setter/getter

Returns

string|null

getFrom() public

getFrom()

Gets "from" address.

Returns

array

getHeaderCharset() public

getHeaderCharset()

HeaderCharset getter.

Returns

string

Charset

getHeaders() public

getHeaders(array $include)

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(array $include, string $eol, ?\Closure $callback)

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

See Also

\Cake\Mailer\Message::getHeaders()

getMessageId() public

getMessageId()

Gets message ID.

Returns

bool|string

getOriginalSubject() public

getOriginalSubject()

Get original subject without encoding

Returns

string

Original subject

getPriority() public

getPriority()

Gets priority.

Returns

int|null

getReadReceipt() public

getReadReceipt()

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

Returns

array

getReplyTo() public

getReplyTo()

Gets "Reply-To" address.

Returns

array

getReturnPath() public

getReturnPath()

Gets return path.

Returns

array

getSender() public

getSender()

Gets "sender" address.

Returns

array

getSubject() public

getSubject()

Gets subject.

Returns

string

getTo() public

getTo()

Gets "to" address

Returns

array

getTransferEncoding() public

getTransferEncoding()

TransferEncoding getter.

Returns

string|null

Encoding

jsonSerialize() public

jsonSerialize()

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

Returns

array

Serializable array of configuration properties.

Throws

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

readFile() protected

readFile(mixed $file)

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

Parameters

string|\Psr\Http\Message\UploadedFileInterface $file

The absolute path to the file to read or UploadedFileInterface instance.

Returns

string

File contents in base64 encoding

reset() public

reset()

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

Returns

$this

serialize() public

serialize()

Serializes the Email object.

Returns

string

setAttachments() public

setAttachments(array $attachments)

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(mixed $email, ?string $name)

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)

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)

Set HTML body for message.

Parameters

string $content

Content string

Returns

$this

setBodyText() public

setBodyText(string $content)

Set text body for message.

Parameters

string $content

Content string

Returns

$this

setCc() public

setCc(mixed $email, ?string $name)

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)

Charset setter.

Parameters

string $charset

Character set.

Returns

$this

setConfig() public

setConfig(array $config)

Sets the configuration for this instance.

Parameters

array $config

Config array.

Returns

$this

setDomain() public

setDomain(string $domain)

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, mixed $email, ?string $name)

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)

Sets email format.

Parameters

string $format

Formatting string.

Returns

$this

Throws

InvalidArgumentException

setEmailPattern() public

setEmailPattern(?string $regex)

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, mixed $email, ?string $name, string $throwMessage)

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(mixed $email, ?string $name)

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

HeaderCharset setter.

Parameters

string|null $charset

Character set.

Returns

$this

setHeaders() public

setHeaders(array $headers)

Sets headers for the message

Parameters

array $headers

Associative array containing headers to be set.

Returns

$this

setMessageId() public

setMessageId(mixed $message)

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 $priority)

Sets priority.

Parameters

int|null $priority

1 (highest) to 5 (lowest)

Returns

$this

setReadReceipt() public

setReadReceipt(mixed $email, ?string $name)

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(mixed $email, ?string $name)

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(mixed $email, ?string $name)

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(mixed $email, ?string $name)

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)

Sets subject.

Parameters

string $subject

Subject string.

Returns

$this

setTo() public

setTo(mixed $email, ?string $name)

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 $encoding)

TransferEncoding setter.

Parameters

string|null $encoding

Encoding set.

Returns

$this

Throws

InvalidArgumentException

unserialize() public

unserialize(mixed $data)

Unserializes the Email object.

Parameters

string $data

Serialized string.

validateEmail() protected

validateEmail(string $email, string $context)

Validate email address

Parameters

string $email

Email address to validate

string $context

Which property was set

Throws

InvalidArgumentException
If email address does not validate

wrap() protected

wrap(?string $message, int $wrapLength)

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

Wrapped message

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

The email 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

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.0/class-Cake.Mailer.Message.html