Messages
In This Article
Messages
Zend\Mail\Message
encapsulates a single email message as described in RFCs
822 and
2822. It acts as a value object for
setting mail headers and content.
If desired, multi-part email messages may also be created. This can be done using the zend-mime component, and assigning the generated MIME part to the mail message body.
The Message
class is a value object. It is not capable of sending or storing itself; for
those purposes, you will need to use, respectively, a Transport adapter or
a Storage adapter.
Quick Start
Creating a Message
by instantiating it:
use Zend\Mail\Message;
$message = new Message();
Once you have your Message
instance, you can start adding content or headers.
Let's set who the mail is from, who it's addressed to, a subject, and some
content:
$message->addFrom('matthew@example.org', 'Matthew Somelli');
$message->addTo('foobar@example.com');
$message->setSubject('Sending an email from Zend\Mail!');
$message->setBody('This is the message body.');
You can also add recipients to carbon-copy ("Cc:") or blind carbon-copy ("Bcc:").
$message->addCc('ralph@example.org');
$message->addBcc('enrico@example.org');
If you want to specify an alternate address to which replies may be sent, that can be done, too.
$message->addReplyTo('matthew@example.com', 'Matthew');
Interestingly, RFC-822 allows for multiple "From:" addresses. When you do this,
the first one will be used as the sender, unless you specify a "Sender:"
header. The Message
class allows for this.
/*
* Mail headers created:
* From: Ralph Nader <ralph@example.org>, Enrico Volante <enrico@example.org>
* Sender: Matthew Sommeli <matthew@example.org>
*/
$message->addFrom('ralph@example.org', 'Ralph Nader');
$message->addFrom('enrico@example.org', 'Enrico Volante');
$message->setSender('matthew@example.org', 'Matthew Sommeli');
By default, the Message
class assumes ASCII encoding for your email. If you
wish to use another encoding, you can do so; setting this will ensure all
headers and body content are properly encoded using quoted-printable encoding.
$message->setEncoding('UTF-8');
If you wish to set other headers, you can do that as well.
/*
* Mail headers created:
* X-API-Key: FOO-BAR-BAZ-BAT
*/
$message->getHeaders()->addHeaderLine('X-API-Key', 'FOO-BAR-BAZ-BAT');
Sometimes you may want to provide HTML content, or multi-part content. To do
that, you'll first create a MIME message object, and then set it as the body of
your mail message object. When you do so, the Message
class will automatically
set a "MIME-Version" header, as well as an appropriate "Content-Type" header.
If you are interested in multipart emails or using attachments, read the chapter on Adding Attachments.
If you want a string representation of your email, you can get that:
echo $message->toString();
Finally, you can fully introspect the message, including getting all addresses of recipients and senders, all headers, and the message body.
// Headers
// Note: this will also grab all headers for which accessors/mutators exist in
// the Message object itself.
foreach ($message->getHeaders() as $header) {
echo $header->toString();
// or grab values: $header->getFieldName(), $header->getFieldValue()
}
// The logic below also works for the methods cc(), bcc(), to(), and replyTo()
foreach ($message->getFrom() as $address) {
printf("%s: %s\n", $address->getEmail(), $address->getName());
}
// Sender
$address = $message->getSender();
if (! is_null($address)) {
printf("%s: %s\n", $address->getEmail(), $address->getName());
}
// Subject
echo "Subject: ", $message->getSubject(), "\n";
// Encoding
echo "Encoding: ", $message->getEncoding(), "\n";
// Message body:
echo $message->getBody(); // raw body, or MIME object
echo $message->getBodyText(); // body as it will be sent
Once your message is shaped to your liking, pass it to a mail transport in order to send it!
$transport->send($message);
Configuration Options
The Message
class has no configuration options, and is instead a value object.
Available Methods
isValid
isValid() : bool
Messages without a From
address are invalid, per RFC-2822.
setEncoding
setEncoding(string $encoding) : void
Set the message encoding.
getEncoding
getEncoding() : string
Get the message encoding.
setHeaders
setHeaders(Zend\Mail\Headers $headers) : void
Compose headers.
getHeaders
getHeaders() : Zend\Mail\Headers
Access headers collection, lazy-loading a Headers
instance if none was
previously attached.
setFrom
setFrom(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Set (overwrite) From
addresses. If an associative array is provided, it must
be a set of key/value pairs where the key is the human readable name, and the
value is the email address.
addFrom
addFrom(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressOrList,
string|null $name
) : void
Add a From
address. If an associative array is provided, it must be a set of
key/value pairs where the key is the human readable name, and the value is the
email address.
getFrom
getFrom() : AddressList
Retrieve list of From
senders.
setTo
setTo(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
null|string $name
) : void
Overwrite the address list in the To
recipients. If an associative array is
provided, it must be a set of key/value pairs where the key is the human
readable name, and the value is the email address.
addTo
addTo(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressOrList,
null|string $name
) : void
Add one or more addresses to the To
recipients; appends to the list. If an
associative array is provided, it must be a set of key/value pairs where the key
is the human readable name, and the value is the email address.
getTo
getTo() : AddressList
Access the address list of the To
header. Lazy-loads an AddressList
and
populates the To
header if not previously done.
setCc
setCc(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Set (overwrite) Cc
addresses. If an associative array is provided, it must be
a set of key/value pairs where the key is the human readable name, and the value
is the email address.
addCc
addCc(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Add a Cc
address. If an associative array is provided, it must be a set of
key/value pairs where the key is the human readable name, and the value is the
email address.
getCc
getCc() : AddressList
Retrieve list of Cc
recipients. Lazy-loads an AddressList
and populates the
Cc
header if not previously done.
setBcc
setBcc(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Set (overwrite) Bcc
addresses. If an associative array is provided, it must be
a set of key/value pairs where the key is the human readable name, and the value
is the email address.
addBcc
addBcc(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Add a Bcc
address. If an associative array is provided, it must be a set of
key/value pairs where the key is the human readable name, and the value is the
email address.
getBcc
getBcc() : AddressList
Retrieve list of Bcc
recipients. Lazy-loads an AddressList
and populates
the Bcc
header if not previously done.
setReplyTo
setReplyTo(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Overwrite the address list in the Reply-To
recipients. If an associative array
is provided, it must be a set of key/value pairs where the key is the human
readable name, and the value is the email address.
addReplyTo
addReplyTo(
string|AddressInterface|array|AddressList|Traversable $emailOrAddressList,
string|null $name
) : void
Add one or more addresses to the Reply-To
recipients. If an associative array
is provided, it must be a set of key/value pairs where the key is the human
readable name, and the value is the email address.
getReplyTo
getReplyTo() : AddressList
Access the address list of the Reply-To
header. Lazy-loads an AddressList
and populates the Reply-To
header if not previously done.
setSender
setSender(
string|AddressInterface $emailOrAddress,
null|string $name
) : void
Set the message envelope Sender
header.
getSender
getSender() : null|AddressInterface
Retrieve the sender address, if any.
setSubject
setSubject(string $subject) :void
Set the message subject header value.
getSubject
getSubject() : null|string
Get the message subject header value.
setBody
setBody(null|string|Zend\Mime\Message|object $body) : void
Set the message body. If a generic object is provided, it must implement
__toString()
.
getBody
getBody() : null|string|object
Return the currently set message body. Object return values include
Zend\Mime\Message
instances or objects implementing __toString()
.
getBodyText
getBodyText() : null|string
Get the string-serialized message body text.
toString
toString() : string
Serialize to string.
Found a mistake or want to contribute to the documentation? Edit this page on GitHub!