Attachments

Clients and staff can add files to replies and notes: screenshots, logs, PDFs, exports. Helpdesk Pro treats every file as private data. A file is only ever sent by your site, after the same access check that decides who can read its message, and nothing Helpdesk Pro renders, returns from the API or puts in an email contains a storage, bucket or CDN address.

Who can see a file

A file belongs to one message and takes that message's visibility.

• A file on a public reply can be fetched by everyone who can read the ticket: its requester, its cc's, clients who can read the project's shared tickets, and staff who work the project.
• A file on an internal note is internal too. Only staff who work the project can fetch it. It never appears in the portal, in a client email or in a client's API view.
• A draft (uploaded but not yet sent) can only be fetched by the person who uploaded it, so a composer can show a preview.
• Access follows the ticket at the moment of the request. A cc taken off a ticket loses access to its files at once; a deleted message's files are staff-only; a deleted ticket's files are gone for clients.

Every refusal is a plain 404 Not Found, whether the file does not exist, belongs to a ticket the visitor cannot read, sits on a note, or is someone else's draft.

How files are served

Two routes stream files, and both run the check above on every request:

The {name} part is only there so a browser saves the file under a sensible name; the id decides which file is sent.

Every response is sent with:

• Cache-Control: private, max-age=300 for files on public replies, and private, no-store for internal files and drafts, so no shared cache or CDN keeps a copy.
• X-Content-Type-Options: nosniff and the content type Helpdesk Pro decided at upload (from its checked extension), never the type the uploader's browser claimed.
• Content-Disposition: inline only for raster images (png, jpg, gif, webp). Everything else, including SVG, HTML and text files, downloads.
• A sandboxing Content-Security-Policy, Cross-Origin-Resource-Policy: same-origin, Referrer-Policy: no-referrer and X-Robots-Tag: noindex, nofollow.

There is never a redirect. When files are also kept in a bucket, the site fetches the bytes and sends them itself.

In the desk and the portal, images show as thumbnails that open full size and other files as named chips. An image pasted into an email shows where it sat in the message and is not listed again below. A reader who may not open that file sees only its name.

Upload limits and file types

A dangerous extension hidden inside a file name is neutralized: invoice.php.pdf is stored as invoice_php.pdf. Path parts, quotes and control characters are removed from names. A pasted image with no useful name is named pasted-image-<date>-<time>.png (or the right extension).

Any signed-in person who is not blocked may upload, and staff through the API. Guests may upload only while portal.guest_submissions is on and at least one public project accepts new requests. With attachments.enabled off nobody can upload, but files already attached stay readable.

Storage

Files are stored once per content: the file name on disk is the SHA-256 of its bytes, so the same screenshot sent to three tickets is stored once. They live in user/data/helpdesk-pro/files/ (beside the database). The directory gets a deny-all .htaccess, and files on disk carry no extension, so nothing there is ever run or served by the web server directly.

A private bucket (optional)

With attachments.storage.s3.enabled on and the endpoint, bucket, key and secret filled in, every new file is also uploaded to an S3-compatible bucket (Cloudflare R2, Amazon S3, Backblaze B2, MinIO). The local copy stays the one that is served. When a file is missing locally (a rebuilt server, a moved site), it is fetched back from the bucket on its first request.

The bucket must be private: Helpdesk Pro never gives out bucket URLs. Objects are stored under attachments.storage.s3.prefix with Cache-Control: private, no-store and Content-Disposition: attachment, so even a bucket exposed by mistake would not render them. The secret is never returned by any endpoint.

Cleanup

The hourly attachments.gc job:

1. deletes drafts nobody sent within attachments.draft_hours (24 hours);
2. recomputes each stored file's reference count, repairing counts left behind when a ticket was deleted permanently;
3. deletes stored files nothing uses any more, locally and from the bucket, once attachments.grace_days (7 days) have passed. Uploading the same bytes again during the grace period brings the file back.

A file referenced as the raw source of an email message is kept as long as that message exists.

Settings

On the Attachments tab of the plugin's settings:

The upload flow

The portal's reply box and form, and the desk's composer, all upload the same way. Files go up as soon as they are picked, dropped or pasted, and are attached when the message is sent.

1. Upload each file as a draft. The first upload has no token; the answer carries one. Send that token with every further upload for the same message.
2. Send the message with the token as attachments_token. The message endpoint claims the sender's drafts under that token and attaches them with the message's visibility. A token is used once.

Only drafts the same person uploaded under that token move, and a client can never attach to a note. Files beyond attachments.max_per_message stay drafts and expire.

Without JavaScript, the portal forms post a plain <input type="file" name="attachments[]" multiple> with the message, and the files are stored and claimed the same way.

The three API routes have no MCP tools. AI clients see files as the attachments list on each timeline message.

Related

• Outbound email
• Inbound email
• People and privacy