Outbound Email Attachments Developer Guide

Outbound email: attachments and pictures — Developer Guide

Fixes #158 · Changelog #2045–#2049, #2055, #2081 · Shipped in 2.10.0 · Corrected in 2.10.1

⚠️ 2.10.0 declared INLINE_THREAD_BUDGET below the code that sends, so any reply quoting a picture from the ticket died with Undefined constant. Section 3 now shows where it lives and why. The write-up: Replies with a picture in the thread failed to send.

How a reply or forward becomes an email, on each of the three providers, and what changed to make attachments and pictures actually arrive. For the bug report itself and what it meant for users, see Reply attachments never reached the customer.

Thanks to An Duong (@duongtuanan), who reported it with the raw message Exchange received — the single line Content-Type: text/html that made the cause obvious — and to @mbsouth, who confirmed it on Forward.

---

The journey of one reply

api/tickets/send_email.php
   │
   ├─ buildFullEmailBody()        analyst's HTML + "reply above this line" + quoted thread
   │
   ├─ provider = Microsoft ─► buildEmailMessage()  ─► JSON { body, attachments[] } ─► Graph sendMail
   │                              └─ processInlineImages() + uploadedFileParts()
   │
   └─ provider = SMTP / Gmail ─► processInlineImages() + uploadedFileParts()
                                   └─ mimeBuildMessage()  (includes/mime_message.php)
                                        ├─ SMTP:  imapSmtpSend()   writes it down the socket
                                        └─ Gmail: gmailSendEmail() posts it, base64url, to the API

The key idea: all three providers are now fed the same list of files. Microsoft takes that list as JSON and builds the email itself; SMTP and Gmail need a finished email, and mimeBuildMessage() builds it from the same list.

---

📁 Files

🧱 builder · 📤 send · 🖼️ pictures · 🧪 test

🎨	File	What it does
🧱	includes/mime_message.php	New. mimeBuildMessage() — the raw RFC 5322 / MIME message for SMTP and Gmail
📤	api/tickets/send_email.php	Chooses the provider; gathers the files; processInlineImages(), uploadedFileParts()
📤	includes/mailbox_imap.php	imapSmtpSend() — the dependency-free SMTP client; now takes $parts
📤	includes/gmail.php	gmailSendEmail() — now takes $cc and $parts
🧪	tests/outbound-email-mime.php	29 checks, including a real SMTP round trip to a fake server

Also benefit, untouched: includes/template_email.php, includes/self_service_email.php, api/auth/request_password_reset.php and workflow/includes/engine.php call the same two send functions without $parts, so they get the plain HTML email they always did — plus, on SMTP, the new Date and Message-ID headers.

---

1. The file list — one shape for three providers

Everything is expressed in Microsoft Graph's fileAttachment shape, because the Graph path already used it:

['name' => 'report.pdf', 'contentType' => 'application/pdf',
 'contentBytes' => '<base64>',                       // an ordinary attachment
 'contentId' => 'inline_image_1_1790805999', 'isInline' => true]   // add these two for a picture in the body

The analyst's uploaded files are converted by one small function, now shared by all three paths:

function uploadedFileParts($attachments) {
    $parts = [];
    foreach ((array)$attachments as $attachment) {
        if (!is_array($attachment) || !isset($attachment['name'], $attachment['content'])) {
            continue;
        }
        $parts[] = [
            '@odata.type' => '#microsoft.graph.fileAttachment',
            'name' => $attachment['name'],
            'contentType' => $attachment['type'] ?? 'application/octet-stream',
            'contentBytes' => $attachment['content'] // Already base64 encoded
        ];
    }
    return $parts;
}

And the send itself:

if ($provider === 'imap' || $provider === 'google') {
    $inline = processInlineImages($bodyForSending, (int)$ticketId);
    $parts  = array_merge($inline['attachments'], uploadedFileParts($attachments));
    if ($provider === 'imap') {
        imapSmtpSend($mailbox, $to, $cc, $subject, $inline['body'], $parts);
    } else {
        gmailSendEmail($accessToken, $to, $subject, $inline['body'], $mailbox['target_mailbox'] ?? '', $cc, $parts);
    }
} else {
    $message = buildEmailMessage($to, $cc, $subject, $bodyForSending, $attachments, (int)$ticketId);
    $result  = sendEmailViaGraph($accessToken, $message);
}

Before the fix the first branch was two separate calls that passed $bodyForSending and nothing else. The ticket then saved $attachments as "sent", so everything on FreeITSM's side said the customer had the file.

2. The message builder

mimeBuildMessage() builds the email only as deep as it needs to be:

The reply has	Structure
Just text	text/html — byte-for-byte the shape sent before #158
Pictures in the body	multipart/related { html, image, image… }
Attached files	multipart/mixed { html-or-related, file, file… }

$body = mimeHtmlPart((string)($m['html'] ?? ''));
if ($inline) {
    $body = mimeMultipart('related', array_merge([$body], array_map('mimeFilePart', $inline)), 'type="text/html"');
}
if ($files) {
    $body = mimeMultipart('mixed', array_merge([$body], array_map('mimeFilePart', $files)));
}
// $body is [headers, content]; its headers become the message's own.
return implode("\r\n", array_merge($headers, $body[0])) . "\r\n\r\n" . $body[1];

Each entity is a [headers, content] pair, so nesting is just wrapping: a related becomes one entity inside a mixed. Everything is base64 in 76-character lines, so no body line can ever begin with the . that would end an SMTP DATA block (the SMTP client dot-stuffs anyway).

Nothing from the browser reaches a header unchecked

A file's name and type come from the analyst's browser, so they are treated as hostile:

// Only a plain type/subtype reaches the header
$type = strtolower((string)($p['contentType'] ?? ''));
if (!preg_match('#^[a-z0-9][a-z0-9!\#$&^_.+-]*/[a-z0-9][a-z0-9!\#$&^_.+-]*$#', $type)) {
    $type = 'application/octet-stream';
}
// An ASCII fallback name, plus RFC 2231 for the real UTF-8 name
$name  = str_replace(["\r", "\n", '"', '\\'], '', $name);
$ascii = preg_replace('/[^\x20-\x7E]/', '_', $name);
$fileParam = 'filename="' . $ascii . '"';
if ($ascii !== $name) {
    $fileParam .= "; filename*=UTF-8''" . rawurlencode($name);
}

The test sends a type of application/pdf\r\nBcc: evil@example.test and checks no Bcc: header appears. Recipients go through FILTER_VALIDATE_EMAIL on both paths, and the subject and sender name are RFC 2047-encoded with line breaks removed.

Date and Message-ID (#2055)

RFC 5322 requires both, and spam filters score a message without them. The Gmail API stamps its own (the raw sent copies show Date: and Message-Id: <…@mail.gmail.com> that FreeITSM never wrote), but nothing on the SMTP path did. So they're added on request, and only imapSmtpSend() asks:

if (!empty($m['envelope'])) {
    $headers[] = 'Date: ' . gmdate('D, d M Y H:i:s') . ' +0000';
    $headers[] = 'Message-ID: ' . mimeMessageId($from);   // <random.time@sender-domain>
}

3. Pictures: processInlineImages()

A picture in an email body only displays if it travels inside the email, referenced as src="cid:…". Two kinds of picture needed converting.

Pictures in the quoted thread

When an email with pictures arrives, FreeITSM saves each picture and rewrites its tag to point back at itself:

<img src="/api/tickets/get_attachment.php?cid=image001.png@01DC...&email_id=326">

Every reply quotes the thread, so that link travels to the customer, whose mail client can't reach it. The converter existed, but looked for api/get_attachment.php — a form no stored email contains. It had converted nothing, on any provider. The pattern now takes any relative link, in any of the forms that have been stored:

$pattern = '/src=(["\'])(?![a-z][a-z0-9+.\-]*:)[^"\']*?api\/(?:tickets\/)?get_attachment\.php\?([^"\']+)\1/i';

The (?!…:) refuses anything with a scheme, so https://someone-else/api/get_attachment.php is left alone.

Only this ticket's files. The old lookup took any attachment id. An analyst can edit a reply's HTML source, so a typed-in link could have mailed out another ticket's — on a multi-company install, another company's — file. Both lookups now join to the email's ticket:

$sql = "SELECT a.id, a.filename, a.content_type, a.file_path
          FROM email_attachments a
          JOIN emails e ON e.id = a.email_id
         WHERE a.id = ? AND e.ticket_id = ?";

At most 2 MB per email. Every reply re-sends the whole thread's pictures, and Graph refuses a request over 4 MB. Uncapped, a picture-heavy thread would have gone from "sends with broken pictures" to "doesn't send" — on Microsoft, which was never reported broken. Past the cap a picture keeps its link, as before:

// At the TOP of send_email.php, under the require_once lines:
const INLINE_THREAD_BUDGET = 2 * 1024 * 1024;

// ...and inside processInlineImages():
$size = (int)filesize($filePath);
if ($threadBytes + $size > INLINE_THREAD_BUDGET) {
    return $matches[0];          // leave this one as a link
}
$threadBytes += $size;

🔴 The constant must stay at the top. A function anywhere in a PHP file exists as soon as the file starts; a top-level const exists only once execution reaches its line. send_email.php does its work at the top and keeps its functions below, so a constant declared down beside processInlineImages() — where 2.10.0 put it — is never defined when a reply is sent. It was read only when a thread picture from the ticket was found, so 2.10.0 failed exactly those replies and sent the rest (#2081).

The picture callback catches Throwable, not just Exception, so a fault embedding one picture leaves that link as it was rather than failing the whole email:

} catch (Throwable $e) {
    error_log('Inline image processing error: ' . $e->getMessage());
    return $matches[0];
}

The same picture quoted twice goes in once ($byAttachmentId).

Pasted screenshots

The reply editor stores a pasted screenshot as a data: image, and Gmail and Outlook won't show a data: image in a received email. Each one becomes an inline part:

$body = preg_replace_callback(
    '/src=(["\'])data:(image\/[a-z0-9.+\-]+);base64,([A-Za-z0-9+\/=\s]+)\1/i',
    function ($m) use (&$inlineAttachments, &$cidCounter, $stamp) {
        $bytes = preg_replace('/\s+/', '', $m[3]);
        if (base64_decode($bytes, true) === false) {
            return $m[0];
        }
        // ... add ['contentType' => $m[2], 'contentBytes' => $bytes, 'contentId' => $newCid, 'isInline' => true]
        return 'src="cid:' . $newCid . '"';
    },
    $body
);

These aren't counted against the 2 MB thread budget: they are the analyst's own content, like an attachment.

---

4. The red herring: pictures "missing" in Gmail

After the fix, a live reply with a pasted screenshot arrived in Gmail showing an empty box where the picture should be, with the picture listed as an attachment underneath. It looked exactly like a broken cid: reference. It wasn't one, and it's worth recording how that was proved, because the same symptom will turn up again.

1. The sent copy was pulled back through the Gmail API: valid MIME, one <img src="cid:inline_image_1_…">, a matching Content-ID on an inline image part, and a complete PNG (IEND present, getimagesizefromstring() happy).
2. The received copy (Gmail → Show original → Download) was identical in every way that matters. Gmail had re-encoded it and added a text part, but the cid still matched.
3. Isolation tests, each changing one thing, all displayed correctly: the real screenshot, the real reply's exact HTML, the real subject (so Gmail threaded it into the same conversation), and no width/height.
4. Outlook opened the downloaded .eml perfectly.
5. The answer was on screen all along: the broken messages were in Gmail's Spam folder. Gmail strips images from spam — it keeps the <img> with its width and height, which is the empty box, removes the src, and lists the picture as an attachment. Report as not spam and it appears.

Why spam? The sending domain's SPF record didn't list Google's servers (spf=fail in the received headers, though DKIM passed). That's DNS, not FreeITSM — but it will do the same to your customers. If you send through a Google Workspace mailbox, make sure your domain's SPF includes include:_spf.google.com.

📌 Before hunting an email rendering bug, check which folder it landed in. And compare the received message, not only the sent one — the difference between them is the receiver's doing, not yours.

---

5. How it's tested

php tests/outbound-email-mime.php — 29 checks, against the real code and real data:

#	Section	What it proves
0	Declaration order	Every top-level const in send_email.php is declared above the code that sends (added in 2.10.1 — run against 2.10.0 it fails and names INLINE_THREAD_BUDGET)
1	The builder	Right structure for each case; bytes identical; the injected Bcc refused; UTF-8 names and subjects encoded; Date/Message-ID only with envelope, well-formed and unique
2	A real quoted thread	Every stored picture becomes a cid: part, byte-for-byte the file on disk
3	Another ticket's file	Left as a link — with a positive control: the same link to this ticket's file is embedded
4	The real SMTP client	Sends to a fake server the test starts on 127.0.0.1: multipart/mixed, CC delivered, PDF identical, every picture inside, Date and Message-ID present
5	The 2 MB cap	A ticket over the cap: one picture embedded, the rest left as links
6	A pasted screenshot	A data: image becomes an inline part

Run against the broken code, the test fails where it should: 0 of the thread pictures are converted, and the SMTP section cannot send at all. The Date/Message-ID check was confirmed to fail with the option switched off.

Beyond the test:

• The inbound side is untouched. The reading pane's responses for six inbound emails (22 pictures and files, all three providers) were recorded before and after: byte-for-byte identical. The recording has to save and restore is_read, because opening an email marks it read — the first "before" snapshot differed from itself for that reason.
• Live, from a Gmail mailbox: the attached PDF arrived, and the pasted screenshot displayed inline once the message was moved out of the Spam folder (see section 4).
• Live, 2.10.1, all three providers, through the real endpoint: nine numbered emails — per provider, a reply quoting a thread picture, a plain reply, and a forward with a thread picture, a pasted screenshot and an attached file. All nine arrived. The same tickets on 2.10.0 failed every picture case with the reporter's exact error, and sent nothing.

⚠️ How the test loads the endpoint, and what that hides. send_email.php sends the moment it is loaded, so the test evals only the functions (from getMailboxForTicket() down) and then the file's top-level constants. That means the test never runs the file in the server's order — which is how 2.10.0 passed every check while failing in production. Section 0 reads the order from the source to make up for it. If you add a constant, put it at the top; if you add a send path, drive it through the real endpoint as well.

---

Traps for the next person

• "Code that looks like it handles a case" is where bugs hide. buildEmailMessage() called processInlineImages(), so everyone assumed Microsoft embedded thread pictures. The pattern inside matched nothing. Count real matches before believing a converter works.
• A file saved to the ticket is not a file sent. If you add another send path, feed it the same $parts list; don't let the ticket record something the email didn't carry.
• The Graph 4 MB limit applies to the whole request. Anything that adds bytes to every reply needs a budget.
• Only SMTP gets envelope. Gmail stamps its own Date and Message-ID.
• An empty box in Gmail may be Spam, not you. See section 4.
• A top-level const is not hoisted. In an endpoint, declare it above the working code, never beside the function that uses it. A test that loads only the functions cannot tell the difference.

Related

• Replies with a picture in the thread failed to send — the 2.10.0 fault
• Reply attachments never reached the customer — the bug write-up
• Basic IMAP mailboxes
• Bugs resolved