Getting Started

Minimal Setup

Installation:
```
composer require symfony/mime
```
No additional configuration is required—just autoload the package. The latest v5.4.54 release (with equivalent patches on 6.4 / 7.x / 8.x) is a security release that tightens header and address validation; see Validation and Sanitization below before upgrading.

First Use Case: Create a simple email with HTML content and an attachment:

use Symfony\Component\Mime\Email;
use Symfony\Component\Mime\Part\DataPart;

$email = (new Email())
    ->from('[email protected]')
    ->to('[email protected]')
    ->subject('Hello!')
    ->html('<h1>Hello!</h1>');

// Add an attachment
$file = new DataPart(file_get_contents('document.pdf'));
$file->filename = 'document.pdf';
$file->contentDisposition = 'attachment';
$email->attach($file);

// Send via Symfony Mailer (what Laravel >= 9 uses under the hood)
$transport = new \Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport(
    'smtp.example.com', 587
);
$transport->setUsername('user');
$transport->setPassword('pass');

$mailer = new \Symfony\Component\Mailer\Mailer($transport);
$mailer->send($email);

Note: SwiftMailer is abandoned—both Symfony Mailer and Laravel >= 9 use Symfony Mime under the hood, so wire this up via Mail::send() / Mail::to()->send($mailable) rather than new Swift_Mailer(...).

Key Classes to Explore:
- Email: For composing emails.
- Message: For raw MIME message manipulation.
- DataPart: For attachments or embedded content.
- File (Symfony\Component\Mime\Part\File): For detecting MIME types of files.

Implementation Patterns

Common Workflows

1. Composing Emails

Dynamic Content: Use ->html() or ->text() with template variables:

$email = (new Email())
    ->html(view('emails.welcome', ['user' => $user]));

Alternatives/Related Parts: For multipart emails (e.g., HTML + text fallback):

$email = (new Email())
    ->html('<h1>HTML</h1>')
    ->text('Plain text fallback')
    ->priority(Email::PRIORITY_HIGH);

2. Handling Attachments

Inline vs. Attachments:

// Inline (e.g., embedded images)
$image = new DataPart(file_get_contents('image.jpg'));
$image->contentId = 'logo';
$email->embed($image);

// Attachment
$file = new DataPart(file_get_contents('report.pdf'));
$file->filename = 'report.pdf';
$file->contentDisposition = 'attachment';
$email->attach($file);

Laravel Integration: Compose with Symfony\Component\Mime\Email and hand off via Mailable::withSymfonyMessage():

use Symfony\Component\Mime\Email;

class WelcomeMail extends Mailable {
    public function build() {
        $email = (new Email())
            ->from('[email protected]')
            ->to($this->user->email)
            ->subject('Welcome!')
            ->html($this->renderView());

        return $this->view('emails.welcome')
                    ->withSymfonyMessage($email);
    }
}

3. Parsing Incoming Emails

Extract Data from Raw MIME:

use Symfony\Component\Mime\Email;

$rawEmail = file_get_contents('email.eml');
$email = Email::fromString($rawEmail);

// Access headers
$subject = $email->getSubject();
$from = $email->getFrom()[0]->getAddress();

// Access attachments
foreach ($email->getAttachments() as $attachment) {
    file_put_contents("attachments/{$attachment->getFilename()}", $attachment->bodyToString());
}

4. MIME Type Detection

For Uploaded Files:

use Symfony\Component\Mime\Part\File;

$file = new File('/path/to/uploaded/file.pdf');
$mimeType = $file->getMimeType(); // e.g., 'application/pdf'

Custom Guessers: Register additional MIME type guessers (e.g., for proprietary formats):

use Symfony\Component\Mime\MimeTypes;

$mimeTypes = new MimeTypes();
$mimeTypes->addType('application/vnd.myformat', 'myfile');
$mimeType = $mimeTypes->guessMimeType('document.myfile');

5. Validation and Sanitization

Reject Malformed Addresses: Addresses are validated as they are constructed. Beyond the earlier hardening (line breaks, user@[invalid], per CVE-2026-45067), the v5.4.54 security release adds:
- Rejection of an unquoted @ in the local part of an address (e.g. user@[email protected]).
- An @ inside a quoted local part is no longer treated as the addr-spec separator, fixing "user@external"@example.com-style addresses.
- Rejection of header names containing non-printable or non-ASCII characters.
- No raw control characters are ever emitted in a header value. These close header-injection and address-spoofing vectors. Audit any place you construct Address/Headers from user input—code relying on lenient parsing will now throw.

Custom Validation: Extend Email or use Symfony’s Validator:

use Symfony\Component\Validator\Constraints as Assert;

$email = new Email();
$email->setTo(new Address('[email protected]', 'User'));
$violations = $validator->validate($email->getTo()[0], [
    new Assert\Email(),
]);

Integration Tips

Laravel-Specific Patterns

Build on Symfony Mime inside a Mailable:

class CustomMailer extends Mailable {
    public function build() {
        $email = (new Email())
            ->from(config('mail.from.address'))
            ->to($this->recipient)
            ->subject($this->subject)
            ->html($this->renderView());

        return $this->view('emails.custom')
                    ->withSymfonyMessage($email);
    }
}

Queue Email Processing: Use Laravel queues to handle bulk emails efficiently:

class SendEmailJob implements ShouldQueue {
    public function handle() {
        Mail::to('[email protected]')->send(
            (new Email())
                ->from('[email protected]')
                ->subject('Your Update')
                ->html('...')
        );
    }
}

File Uploads with MIME Detection: Validate uploads before storage:

use Symfony\Component\Mime\Part\File;

public function store(Request $request) {
    $file = new File($request->file('document')->getPathname());
    $mimeType = $file->getMimeType();

    if (!str_starts_with($mimeType, 'application/pdf')) {
        throw new \Exception('Invalid file type');
    }

    // Store file...
}

Performance Optimizations

Cache MIME Type Guessers: Cache results for frequently accessed files:

$cache = new \Symfony\Component\Cache\Simple\FilesystemCache();
$file = new File('document.pdf');
$mimeType = $cache->get('mime_type_' . $file->getPathname(), function() use ($file) {
    return $file->getMimeType();
});

Batch Processing: Process emails in chunks for bulk operations:

$emails = Email::fromString($rawBatch);
foreach ($emails as $email) {
    // Process each email (e.g., parse, store, or forward)
}

Gotchas and Tips

Pitfalls and Debugging

1. MIME Type Detection Issues

Problem: File::getMimeType() returns incorrect results for custom file types.

Fix: Register custom MIME types:

$mimeTypes = new MimeTypes();
$mimeTypes->addType('application/vnd.myapp', 'myext');
$file = new File('document.myapp', null, $mimeTypes);
$mimeType = $file->getMimeType(); // Now returns 'application/vnd.myapp'

Debugging: Use File::getMimeTypeGuesser() to inspect guessers:

$guesser = $file->getMimeTypeGuesser();
$guesser->guessMimeType('document.pdf'); // Debug individual guessers

2. Email Address Validation

Problem: Custom email addresses (e.g., [email protected]) may be rejected.

Fix: Use Address with custom validation:

use Symfony\Component\Mime\Address;

$address = new Address('[email protected]');
if (!$address->isValid()) {
    throw new \InvalidArgumentException('Invalid email address');
}

3. Attachment Filenames and Content-Disposition

Problem: Filenames in attachments are overwritten by Content-ID in some versions.

Fix: Explicitly set filename and contentDisposition:

$attachment = new DataPart(file_get_contents('file.pdf'));
$attachment->filename = 'custom_name.pdf';
$attachment->contentDisposition = 'attachment';
$email->attach($attachment);

4. Stricter Header-Name Validation (v5.4.54+)

Problem: Custom headers whose name contains non-ASCII or non-printable characters now throw at construction time, rather than being smuggled into the wire format. Tests that previously asserted on a lenient raw output will fail.

Fix: Use RFC 5322 field-name characters (printable ASCII, no :, no whitespace, no CR/LF):

$email->getHeaders()->addTextHeader('X-App-Version', '1.0'); // OK
// $email->getHeaders()->addTextHeader("X-App-Version\r\nBcc", '...'); // rejected

5. `@` Handling in Local Parts and Domains (v5.4.54+)

Problem: An unquoted @ in the local part (user@[email protected]) is now rejected. Conversely, a quoted local part containing @ ("user@external"@example.com) is now parsed correctly instead of the domain being split off at the first @.

Fix: Quote any local part that legitimately contains @; otherwise, let validation fail fast:

new Address('"user@external"@example.com'); // valid — quoted local part
// new Address('user@[email protected]');     // rejected as of v5.4.54

6. Control Characters in Header Values

Problem: Subjects and custom headers built from user input may be sanitized or rejected at emit time—raw CR/LF and other C0 controls are no longer emitted. Tests asserting on a hand-built MIME string can fail unexpectedly.

Fix: Normalize input at the boundary and assert on the rendered toString() output instead:

$subject = preg_replace('/[\x00-\x1F\x7F]/', '', $userInput);
$email->subject($subject);

Extension Points

Custom MimeTypeGuesserInterface implementations via MimeTypes::registerGuesser().
Custom address validators if the default rules are too strict for your upstream providers (e.g., legacy addresses with unusual quoted local parts)—but do not relax header-name or header-value rules; those are the actual security boundary being hardened in v5.4.54.

Mime Laravel Package