Creating Messages

The Structure of a Message

Of all of the MIME entities, a message -- Swift_Message is the largest and most complex. It has many properties that can be updated and it can contain other MIME entities -- attachments for example -- nested inside it.

A Message has a lot of different Headers which are there to present information about the message to the recipients' mail client. Most of these headers will be familiar to the majority of users, but we'll list the basic ones. Although it's possible to work directly with the Headers of a Message (or other MIME entity), the standard Headers have accessor methods provided to abstract away the complex details for you. For example, although the Date on a message is written with a strict format, you only need to pass a DateTimeInterface instance to setDate().

Working with a Message Object

Although there are a lot of available methods on a message object, you only need to make use of a small subset of them. Usually you'll use setSubject(), setTo() and setFrom() before setting the body of your message with setBody():

1
2

$message = new Swift_Message();
$message->setSubject('My subject');

All MIME entities (including a message) have a toString() method that you can call if you want to take a look at what is going to be sent. For example, if you echo $message->toString(); you would see something like this:

1
2
3
4
5
6
7
8
9
10

Message-ID: 
Date: Thu, 25 Dec 2008 13:54:38 +1100
Subject: Example subject
From: Chris Corbyn 
To: Receiver Name 
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable

Here is the message

We'll take a closer look at the methods you use to create your message in the following sections.

Setting the Subject Line

The subject line, displayed in the recipients' mail client can be set with the setSubject() method, or as a parameter to new Swift_Message():

1
2
3
4
5

// Pass it as a parameter when you create the message
$message = new Swift_Message('My amazing subject');

// Or set it after like this
$message->setSubject('My amazing subject');

Setting the Body Content

The body of the message -- seen when the user opens the message -- is specified by calling the setBody() method. If an alternative body is to be included, addPart() can be used.

The body of a message is the main part that is read by the user. Often people want to send a message in HTML format (text/html), other times people want to send in plain text (text/plain), or sometimes people want to send both versions and allow the recipient to choose how they view the message.

As a rule of thumb, if you're going to send a HTML email, always include a plain-text equivalent of the same content so that users who prefer to read plain text can do so.

If the recipient's mail client offers preferences for displaying text vs. HTML then the mail client will present that part to the user where available. In other cases the mail client will display the "best" part it can - usually HTML if you've included HTML:

1
2
3
4
5
6
7
8

// Pass it as a parameter when you create the message
$message = new Swift_Message('Subject here', 'My amazing body');

// Or set it after like this
$message->setBody('My <em>amazing</em> body', 'text/html');

// Add alternative parts with addPart()
$message->addPart('My amazing body in plain text', 'text/plain');

Attaching Existing Files

Files that already exist, either on disk or at a URL can be attached to a message with just one line of code, using Swift_Attachment::fromPath().

You can attach files that exist locally, or if your PHP installation has allow_url_fopen turned on you can attach files from other websites.

The attachment will be presented to the recipient as a downloadable file with the same filename as the one you attached:

1
2
3
4
5
6
7
8
9
10
11
12

// Create the attachment
// * Note that you can technically leave the content-type parameter out
$attachment = Swift_Attachment::fromPath('/path/to/image.jpg', 'image/jpeg');

// Attach it to the message
$message->attach($attachment);

// The two statements above could be written in one line instead
$message->attach(Swift_Attachment::fromPath('/path/to/image.jpg'));

// You can attach files from a URL if allow_url_fopen is on in php.ini
$message->attach(Swift_Attachment::fromPath('http://site.tld/logo.png'));

Setting the Filename

Usually you don't need to explicitly set the filename of an attachment because the name of the attached file will be used by default, but if you want to set the filename you use the setFilename() method of the Attachment.

The attachment will be attached in the normal way, but meta-data sent inside the email will rename the file to something else:

1
2
3
4
5
6
7
8

// Create the attachment and call its setFilename() method
$attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
  ->setFilename('cool.jpg');

// Because there's a fluid interface, you can do this in one statement
$message->attach(
  Swift_Attachment::fromPath('/path/to/image.jpg')->setFilename('cool.jpg')
);

Attaching Dynamic Content

Files that are generated at runtime, such as PDF documents or images created via GD can be attached directly to a message without writing them out to disk. Use Swift_Attachment directly.

The attachment will be presented to the recipient as a downloadable file with the filename and content-type you specify:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// Create your file contents in the normal way, but don't write them to disk
$data = create_my_pdf_data();

// Create the attachment with your data
$attachment = new Swift_Attachment($data, 'my-file.pdf', 'application/pdf');

// Attach it to the message
$message->attach($attachment);


// You can alternatively use method chaining to build the attachment
$attachment = (new Swift_Attachment())
  ->setFilename('my-file.pdf')
  ->setContentType('application/pdf')
  ->setBody($data)
  ;

Changing the Disposition

Attachments just appear as files that can be saved to the Desktop if desired. You can make attachment appear inline where possible by using the setDisposition() method of an attachment.

The attachment will be displayed within the email viewing window if the mail client knows how to display it:

1
2
3
4
5
6
7
8
9

// Create the attachment and call its setDisposition() method
$attachment = Swift_Attachment::fromPath('/path/to/image.jpg')
  ->setDisposition('inline');


// Because there's a fluid interface, you can do this in one statement
$message->attach(
  Swift_Attachment::fromPath('/path/to/image.jpg')->setDisposition('inline')
);

Embedding Inline Media Files

Often, people want to include an image or other content inline with a HTML message. It's easy to do this with HTML linking to remote resources, but this approach is usually blocked by mail clients. Swift Mailer allows you to embed your media directly into the message.

Mail clients usually block downloads from remote resources because this technique was often abused as a mean of tracking who opened an email. If you're sending a HTML email and you want to include an image in the message another approach you can take is to embed the image directly.

Swift Mailer makes embedding files into messages extremely streamlined. You embed a file by calling the embed() method of the message, which returns a value you can use in a src or href attribute in your HTML.

Just like with attachments, it's possible to embed dynamically generated content without having an existing file available.

The embedded files are sent in the email as a special type of attachment that has a unique ID used to reference them within your HTML attributes. On mail clients that do not support embedded files they may appear as attachments.

Although this is commonly done for images, in theory it will work for any displayable (or playable) media type. Support for other media types (such as video) is dependent on the mail client however.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// Create the message
$message = new Swift_Message('My subject');

// Set the body
$message->setBody(
'<html>' .
' <body>' .
'  Here is an image <img src="' . // Embed the file
     $message->embed(Swift_Image::fromPath('image.png')) .
   '" alt="Image" />' .
'  Rest of message' .
' </body>' .
'</html>',
  'text/html' // Mark the content-type as HTML
);

// You can embed files from a URL if allow_url_fopen is on in php.ini
$message->setBody(
'<html>' .
' <body>' .
'  Here is an image <img src="' .
     $message->embed(Swift_Image::fromPath('http://site.tld/logo.png')) .
   '" alt="Image" />' .
'  Rest of message' .
' </body>' .
'</html>',
  'text/html'
);

1
2
3
4
5
6
7
8
9
10
11
12
13

// If placing the embed() code inline becomes cumbersome
// it's easy to do this in two steps
$cid = $message->embed(Swift_Image::fromPath('image.png'));

$message->setBody(
'<html>' .
' <body>' .
'  Here is an image <img src="' . $cid . '" alt="Image" />' .
'  Rest of message' .
' </body>' .
'</html>',
  'text/html' // Mark the content-type as HTML
);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Create your file contents in the normal way, but don't write them to disk
$img_data = create_my_image_data();

// Create the message
$message = new Swift_Message('My subject');

// Set the body
$message->setBody(
'<html>' .
' <body>' .
'  Here is an image <img src="' . // Embed the file
     $message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg')) .
   '" alt="Image" />' .
'  Rest of message' .
' </body>' .
'</html>',
  'text/html' // Mark the content-type as HTML
);

1
2
3
4
5
6
7
8
9
10
11
12
13

// If placing the embed() code inline becomes cumbersome
// it's easy to do this in two steps
$cid = $message->embed(new Swift_Image($img_data, 'image.jpg', 'image/jpeg'));

$message->setBody(
'<html>' .
' <body>' .
'  Here is an image <img src="' . $cid . '" alt="Image" />' .
'  Rest of message' .
' </body>' .
'</html>',
  'text/html' // Mark the content-type as HTML
);

Setting To: Recipients

To: recipients are required in a message and are set with the setTo() or addTo() methods of the message.

To set To: recipients, create the message object using either new Swift_Message( ... ), then call the setTo() method with a complete array of addresses, or use the addTo() method to iteratively add recipients.

The setTo() method accepts input in various formats as described earlier in this chapter. The addTo() method takes either one or two parameters. The first being the email address and the second optional parameter being the name of the recipient.

To: recipients are visible in the message headers and will be seen by the other recipients:

1
2
3
4
5
6
7
8

// Using setTo() to set all recipients in one go
$message->setTo([
  'person1@example.org',
  'person2@otherdomain.org' => 'Person 2 Name',
  'person3@example.org',
  'person4@example.org',
  'person5@example.org' => 'Person 5 Name'
]);

1
2
3

// Using addTo() to add recipients iteratively
$message->addTo('person1@example.org');
$message->addTo('person2@example.org', 'Person 2 Name');

Setting Cc: Recipients

Cc: recipients are set with the setCc() or addCc() methods of the message.

To set Cc: recipients, create the message object using either new Swift_Message( ... ), then call the setCc() method with a complete array of addresses, or use the addCc() method to iteratively add recipients.

The setCc() method accepts input in various formats as described earlier in this chapter. The addCc() method takes either one or two parameters. The first being the email address and the second optional parameter being the name of the recipient.

Cc: recipients are visible in the message headers and will be seen by the other recipients:

1
2
3
4
5
6
7
8

// Using setTo() to set all recipients in one go
$message->setTo([
  'person1@example.org',
  'person2@otherdomain.org' => 'Person 2 Name',
  'person3@example.org',
  'person4@example.org',
  'person5@example.org' => 'Person 5 Name'
]);

1
2
3

// Using addCc() to add recipients iteratively
$message->addCc('person1@example.org');
$message->addCc('person2@example.org', 'Person 2 Name');

Setting Bcc: Recipients

Bcc: recipients receive a copy of the message without anybody else knowing it, and are set with the setBcc() or addBcc() methods of the message.

To set Bcc: recipients, create the message object using either new Swift_Message( ... ), then call the setBcc() method with a complete array of addresses, or use the addBcc() method to iteratively add recipients.

The setBcc() method accepts input in various formats as described earlier in this chapter. The addBcc() method takes either one or two parameters. The first being the email address and the second optional parameter being the name of the recipient.

Only the individual Bcc: recipient will see their address in the message headers. Other recipients (including other Bcc: recipients) will not see the address:

1
2
3
4
5
6
7
8

// Using setBcc() to set all recipients in one go
$message->setBcc([
  'person1@example.org',
  'person2@otherdomain.org' => 'Person 2 Name',
  'person3@example.org',
  'person4@example.org',
  'person5@example.org' => 'Person 5 Name'
]);

1
2
3

// Using addBcc() to add recipients iteratively
$message->addBcc('person1@example.org');
$message->addBcc('person2@example.org', 'Person 2 Name');

1
2
3
4

$smtpUtf8 = new Swift_Transport_Esmtp_SmtpUtf8Handler();
$transport->setExtensionHandlers([$smtpUtf8]);
$utf8Encoder = new Swift_AddressEncoder_Utf8AddressEncoder();
$transport->setAddressEncoder($utf8Encoder);

Setting the From: Address

A From: address is required and is set with the setFrom() method of the message. From: addresses specify who actually wrote the email, and usually who sent it.

What most people probably don't realize is that you can have more than one From: address if more than one person wrote the email -- for example if an email was put together by a committee.

The From: address(es) are visible in the message headers and will be seen by the recipients.

1
2
3
4
5
6
7
8
9
10
11

// Set a single From: address
$message->setFrom('your@address.tld');

// Set a From: address including a name
$message->setFrom(['your@address.tld' => 'Your Name']);

// Set multiple From: addresses if multiple people wrote the email
$message->setFrom([
  'person1@example.org' => 'Sender One',
  'person2@example.org' => 'Sender Two'
]);

Setting the Sender: Address

A Sender: address specifies who sent the message and is set with the setSender() method of the message.

The Sender: address is visible in the message headers and will be seen by the recipients.

This address will be used as the Return-Path: unless otherwise specified.

You must not set more than one sender address on a message because it's not possible for more than one person to send a single message:

1

$message->setSender('your@address.tld');

Setting the Return-Path: (Bounce) Address

The Return-Path: address specifies where bounce notifications should be sent and is set with the setReturnPath() method of the message.

You can only have one Return-Path: and it must not include a personal name.

Bounce notifications will be sent to this address:

1

$message->setReturnPath('bounces@address.tld');

S/MIME

S/MIME can sign and/or encrypt a message using the OpenSSL extension.

When signing a message, the signer creates a signature of the entire content of the message (including attachments).

The certificate and private key must be PEM encoded, and can be either created using for example OpenSSL or obtained at an official Certificate Authority (CA).

The recipient must have the CA certificate in the list of trusted issuers in order to verify the signature.

Make sure the certificate supports emailProtection.

When using OpenSSL this can done by the including the -addtrust emailProtection parameter when creating the certificate:

1
2
3
4
5

$message = new Swift_Message();

$smimeSigner = new Swift_Signers_SMimeSigner();
$smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem');
$message->attachSigner($smimeSigner);

When the private key is secured using a passphrase use the following instead:

1
2
3
4
5

$message = new Swift_Message();

$smimeSigner = new Swift_Signers_SMimeSigner();
$smimeSigner->setSignCertificate('/path/to/certificate.pem', ['/path/to/private-key.pem', 'passphrase']);
$message->attachSigner($smimeSigner);

By default the signature is added as attachment, making the message still readable for mailing agents not supporting signed messages.

Storing the message as binary is also possible but not recommended:

1

$smimeSigner->setSignCertificate('/path/to/certificate.pem', '/path/to/private-key.pem', PKCS7_BINARY);

When encrypting the message (also known as enveloping), the entire message (including attachments) is encrypted using a certificate, and the recipient can then decrypt the message using corresponding private key.

Encrypting ensures nobody can read the contents of the message without the private key.

Normally the recipient provides a certificate for encrypting and keeping the decryption key private.

Using both signing and encrypting is also possible:

1
2
3
4
5
6

$message = new Swift_Message();

$smimeSigner = new Swift_Signers_SMimeSigner();
$smimeSigner->setSignCertificate('/path/to/sign-certificate.pem', '/path/to/private-key.pem');
$smimeSigner->setEncryptCertificate('/path/to/encrypt-certificate.pem');
$message->attachSigner($smimeSigner);

The used encryption cipher can be set as the second parameter of setEncryptCertificate()

See https://secure.php.net/manual/openssl.ciphers for a list of supported ciphers.

By default the message is first signed and then encrypted, this can be changed by adding:

1

$smimeSigner->setSignThenEncrypt(false);

Changing this is not recommended as most mail agents don't support this none-standard way.

Only when having trouble with sign then encrypt method, this should be changed.