The Mime Component

Installation

1

$ composer require symfony/mime

Introduction

MIME (Multipurpose Internet Mail Extensions) is an Internet standard that extends the original basic format of emails to support features like:

• Headers and text contents using non-ASCII characters;
• Message bodies with multiple parts (e.g. HTML and plain text contents);
• Non-text attachments: audio, video, images, PDF, etc.

The entire MIME standard is complex and huge, but Symfony abstracts all that complexity to provide two ways of creating MIME messages:

• A high-level API based on the Email class to quickly create email messages with all the common features;
• A low-level API based on the Message class to have absolute control over every single part of the email message.

Usage

Use the Email class and their chainable methods to compose the entire email message:

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

use Symfony\Component\Mime\Email;

$email = (new Email())
    ->from('fabien@symfony.com')
    ->to('foo@example.com')
    ->cc('bar@example.com')
    ->bcc('baz@example.com')
    ->replyTo('fabien@symfony.com')
    ->priority(Email::PRIORITY_HIGH)
    ->subject('Important Notification')
    ->text('Lorem ipsum...')
    ->html('<h1>Lorem ipsum</h1> <p>...</p>')
;

The only purpose of this component is to create the email messages. Use the Mailer component to actually send them.

Twig Integration

The Mime component comes with excellent integration with Twig, allowing you to create messages from Twig templates, embed images, inline CSS and more. Details on how to use those features can be found in the Mailer documentation: Twig: HTML & CSS.

But if you're using the Mime component without the Symfony framework, you'll need to handle a few setup details.

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

// ...
use Symfony\Bridge\Twig\Mime\BodyRenderer;
use Twig\Environment;
use Twig\Loader\FilesystemLoader;

// when using the Mime component inside a full-stack Symfony application, you
// don't need to do this Twig setup. You only have to inject the 'twig' service
$loader = new FilesystemLoader(__DIR__.'/templates');
$twig = new Environment($loader);

$renderer = new BodyRenderer($twig);
// this updates the $email object contents with the result of rendering
// the template defined earlier with the given context
$renderer->render($email);

1

$ composer require twig/cssinliner-extra

1
2
3
4
5
6

// ...
use Twig\Extra\CssInliner\CssInlinerExtension;

$loader = new FilesystemLoader(__DIR__.'/templates');
$twig = new Environment($loader);
$twig->addExtension(new CssInlinerExtension());

Creating Raw Email Messages

This is useful for advanced applications that need absolute control over every email part. It's not recommended for applications with regular email requirements because it adds complexity for no real gain.

Before continuing, it's important to have a look at the low level structure of an email message. Consider a message which includes some content as both text and HTML, a single PNG image embedded in those contents and a PDF file attached to it. The MIME standard allows structuring this message in different ways, but the following tree is the one that works on most email clients:

1
2
3
4
5
6
7

multipart/mixed
├── multipart/related
│   ├── multipart/alternative
│   │   ├── text/plain
│   │   └── text/html
│   └── image/png
└── application/pdf

This is the purpose of each MIME message part:

• multipart/alternative: used when two or more parts are alternatives of the same (or very similar) content. The preferred format must be added last.
• multipart/mixed: used to send different content types in the same message, such as when attaching files.
• multipart/related: used to indicate that each message part is a component of an aggregate whole. The most common usage is to display images embedded in the message contents.

When using the low-level Message class to create the email message, you must keep all the above in mind to define the different parts of the email by hand:

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

use Symfony\Component\Mime\Header\Headers;
use Symfony\Component\Mime\Message;
use Symfony\Component\Mime\Part\Multipart\AlternativePart;
use Symfony\Component\Mime\Part\TextPart;

$headers = (new Headers())
    ->addMailboxListHeader('From', ['fabien@symfony.com'])
    ->addMailboxListHeader('To', ['foo@example.com'])
    ->addTextHeader('Subject', 'Important Notification')
;

$textContent = new TextPart('Lorem ipsum...');
$htmlContent = new TextPart('<h1>Lorem ipsum</h1> <p>...</p>', null, 'html');
$body = new AlternativePart($textContent, $htmlContent);

$email = new Message($headers, $body);

Embedding images and attaching files is possible by creating the appropriate email multiparts:

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

// ...
use Symfony\Component\Mime\Part\DataPart;
use Symfony\Component\Mime\Part\Multipart\MixedPart;
use Symfony\Component\Mime\Part\Multipart\RelatedPart;

// ...
$embeddedImage = new DataPart(fopen('/path/to/images/logo.png', 'r'), null, 'image/png');
$imageCid = $embeddedImage->getContentId();

$attachedFile = new DataPart(fopen('/path/to/documents/terms-of-use.pdf', 'r'), null, 'application/pdf');

$textContent = new TextPart('Lorem ipsum...');
$htmlContent = new TextPart(sprintf(
    '<img src="cid:%s"/> <h1>Lorem ipsum</h1> <p>...</p>', $imageCid
), null, 'html');
$bodyContent = new AlternativePart($textContent, $htmlContent);
$body = new RelatedPart($bodyContent, $embeddedImage);

$messageParts = new MixedPart($body, $attachedFile);

$email = new Message($headers, $messageParts);

Serializing Email Messages

Email messages created with either the Email or Message classes can be serialized because they are simple data objects:

1
2
3
4
5
6

$email = (new Email())
    ->from('fabien@symfony.com')
    // ...
;

$serializedEmail = serialize($email);

A common use case is to store serialized email messages, include them in a message sent with the Messenger component and recreate them later when sending them. Use the RawMessage class to recreate email messages from their serialized contents:

1
2
3
4
5
6
7

use Symfony\Component\Mime\RawMessage;

// ...
$serializedEmail = serialize($email);

// later, recreate the original message to actually send it
$message = new RawMessage(unserialize($serializedEmail));

MIME Types Utilities

Although MIME was designed mainly for creating emails, the content types (also known as MIME types and "media types") defined by MIME standards are also of importance in communication protocols outside of email, such as HTTP. That's why this component also provides utilities to work with MIME types.

The MimeTypes class transforms between MIME types and file name extensions:

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

use Symfony\Component\Mime\MimeTypes;

$mimeTypes = new MimeTypes();
$exts = $mimeTypes->getExtensions('application/javascript');
// $exts = ['js', 'jsm', 'mjs']
$exts = $mimeTypes->getExtensions('image/jpeg');
// $exts = ['jpeg', 'jpg', 'jpe']

$types = $mimeTypes->getMimeTypes('js');
// $types = ['application/javascript', 'application/x-javascript', 'text/javascript']
$types = $mimeTypes->getMimeTypes('apk');
// $types = ['application/vnd.android.package-archive']

These methods return arrays with one or more elements. The element position indicates its priority, so the first returned extension is the preferred one.

1
2
3
4
5
6

use Symfony\Component\Mime\MimeTypes;

$mimeTypes = new MimeTypes();
$mimeType = $mimeTypes->guessMimeType('/some/path/to/image.gif');
// Guessing is not based on the file name, so $mimeType will be 'image/gif'
// only if the given file is truly a GIF image

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

namespace App;

use Symfony\Component\Mime\MimeTypeGuesserInterface;

class SomeMimeTypeGuesser implements MimeTypeGuesserInterface
{
    public function isGuesserSupported(): bool
    {
        // return true when the guesser is supported (might depend on the OS for instance)
        return true;
    }

    public function guessMimeType(string $path): ?string
    {
        // inspect the contents of the file stored in $path to guess its
        // type and return a valid MIME type ... or null if unknown

        return '...';
    }
}