The Multipart/Mixed Dilemma in PHP Mail
When you transition a PHP mailer from plain text to HTML, the boundary is straightforward: you set the Content-Type header to text/html. This tells the client to parse the body as markup. However, the moment you introduce an attachment, the MIME structure fundamentally changes. You cannot simply append a binary file to an HTML stream; you must wrap the entire message in a container that supports multiple parts. This forces the Content-Type header to become multipart/mixed, which inherently separates the content into distinct sections with different headers.
The core issue developers face is that the main body of a multipart/mixed message often defaults to text/plain. If you simply set the boundary and dump your HTML string, email clients will render it as plain text, stripping away all styling, classes, and layout structures. To achieve an email with both HTML content and attachments, you must explicitly define two distinct body parts: one for the HTML message and one for the attachment.
Defining the MIME Structure
In a multipart/mixed message, every part requires its own boundary string and its own header block. The first part typically holds the main message (the HTML), while subsequent parts hold the attachments. You cannot mix them into a single blob without breaking the parser logic of email clients like Outlook or Apple Mail.
The structure generally looks like this:
- Boundary Declaration: Defines the delimiter string used to separate parts.
- Part 1 (HTML Body):
Content-Type: text/html; charset="UTF-8". This part must carry the actual HTML content you intend to render. - Part 2 (Attachment):
Content-Type: application/pdf(or whatever the file type is). This part carries the binary data of the attachment.
If your PHP mailer logic simply concatenates an attachment stream after a single HTML header, the client sees only one content type for the body or misinterprets the boundary. The solution requires constructing the MIME message manually using CRLF line breaks and ensuring that the Content-Type header for the HTML part is explicitly set before the content is written.
Implementing with PHP Mailer Classes
While raw mail() functions offer minimal control, libraries like phpmailer/phpmailer abstract this complexity but often default to plain text if not configured correctly. When using a library that handles multipart messages automatically, you must ensure the isHTML() method is called to set the body type for the primary part, and then the attachment logic is appended.
If you are constructing the message string manually (e.g., using mail() with a raw header), the code logic resembles this:
$boundary = '==============1234567890';
$headers = "From: sender@example.com\r\n";
$headers .= "MIME-Version: 1.0\r\n";
$headers .= "Content-Type: multipart/mixed; boundary=$boundary\r\n";
$message = "--$boundary\r\n";
// Part 1: HTML Body
$message .= "Content-Type: text/html; charset=UTF-8\r\n";
$message .= "Content-Transfer-Encoding: quoted-printable\r\n";
$message .= "\r\n";
$message .= $htmlBody; // Your HTML content here
$message .= "\r\n";
// Part 2: Attachment
$message .= "--$boundary\r\n";
$message .= "Content-Type: application/pdf; name=\"invoice.pdf\"\r\n";
$message .= "Content-Disposition: attachment; filename=\"invoice.pdf\"\r\n";
$message .= "Content-Transfer-Encoding: base64\r\n";
$message .= "\r\n";
$message .= chunk_split(base64_encode(file_get_contents('path/to/file.pdf')));
// Don't forget the closing boundary
$message .= "--$boundary--\r\n";
mail($to, $subject, $message, $headers);
In this manual approach, the critical decision is setting Content-Type: text/html for the first part. If you omit this or set it to text/plain by default, the HTML tags will be visible to the user rather than rendered. The attachment part must follow with its own boundary prefix (--$boundary) and specific headers indicating it is an attachment.
Trade-offs and Client Behavior
The primary trade-off here is complexity versus compatibility. Some older email clients struggle with multipart/mixed messages where the first part is HTML, preferring a plain text fallback. To mitigate this, many developers implement a "folding" strategy: providing both a text/plain part and a text/html part within the same multipart message, allowing clients to choose the best renderer.
However, for modern web development stacks, ensuring the primary content type is HTML in the first part of the multipart structure is the standard requirement. If you rely on libraries that automatically detect file types, verify that the library does not default the body to plain text unless explicitly told otherwise. Always double-check the Content-Transfer-Encoding header; while quoted-printable is common for text, binary attachments often require base64 encoding to remain safe across different mail transfer agents.
For those working within the Laravel ecosystem, utilizing packages that handle MIME boundaries internally can reduce the risk of syntax errors in the raw message construction. Resources like https://laravelcompany.com offer insights into optimizing email delivery pipelines, particularly when integrating complex attachment logic into high-volume applications.