Raxx · internal docs

internal · gated ↑ index

FreeScout email templates — runbook

System: FreeScout helpdesk — tickets.raxx.app Templates location (repo): freescout/templates/ Resolves: #712 Last updated: 2026-05-04

Overview

This runbook documents the Raxx-branded outbound email templates for FreeScout and the procedure for deploying them to the raxx-tickets Lightsail instance.

Three template types are covered:

Template	File (HTML)	File (text)	Triggered when
Auto-reply	`freescout/templates/autoreply.html`	`freescout/templates/autoreply.txt`	Customer sends a new email to `support@raxx.app`
Operator reply	`freescout/templates/operator-reply.html`	`freescout/templates/operator-reply.txt`	Operator sends a reply to a customer
Notification	`freescout/templates/notification.html`	`freescout/templates/notification.txt`	Ticket status change or system notification sent to customer

All templates satisfy the #712 acceptance criteria:

Raxx wordmark inlined as a base64 data URI (no external image request — CF Access on tickets.raxx.app would silently break external image links in email clients)
Confidence Engine color palette: ink #0f172a, moss #4a7c59, snow #f8f5f0
Footer: Raxx Support | MooseQuest LLC. All rights reserved.
No FreeScout attribution anywhere in the HTML source
Legal footer on all three (investment-advice disclaimer + data-processing notice)
System font stack only — no web fonts (deliverability safety)

Brand tokens reference

Token	Hex	Use in email
ink	`#0f172a`	Header background, body text, ticket metadata
moss	`#4a7c59`	Accent bar, CTA button, reply quote border, status bar
snow	`#f8f5f0`	Page background, ticket context box background
white	`#ffffff`	Card background
secondary text	`#64748b`	Footer copy, label text

Font stack (all templates):

-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif

Logo: Raxx wordmark-c (Direction C, locked 2026-04-25) inlined as a base64 SVG data URI. Source file: docs/design/brand/logos/raxx-wordmark-c.svg To regenerate the data URI if the SVG changes:

base64 -i docs/design/brand/logos/raxx-wordmark-c.svg | tr -d '\n'

Paste the output into the src="data:image/svg+xml;base64,..." attribute in each HTML template.

FreeScout variable reference

FreeScout uses Laravel Blade syntax. Variable names vary slightly by installed version. Verify the exact names on your instance before deploying.

Template placeholder	FreeScout Blade variable (typical)	Fallback if absent
`{{customer.first_name}}`	`$customer->first_name` or `{{ $customer->first_name }}`	Leave blank — "Hi," still reads fine
`{{conversation.subject}}`	`$conversation->subject`	Ticket subject from email thread
`{{conversation.status}}`	`$conversation->status_label`	Current ticket status string
`{{conversation.url}}`	`$conversation->url()`	Link to the specific ticket
`{{{reply_text}}}`	`{!! $reply->body !!}` (raw HTML, Blade unescaped)	Operator reply HTML body
`{{notification.message}}`	Depends on notification type — check each notification Blade partial	Generic update text

The HTML templates use {{ and {{{ as placeholder syntax for readability. When adapting to Blade, replace with the actual Blade directives for your FreeScout version.

Deployment: how FreeScout email templates work

FreeScout uses Laravel Blade templates for all outbound emails. Template files live at:

/var/www/html/freescout/resources/views/emails/

Key files (paths verified on FreeScout 1.8.x — check your installed version):

Template type	Likely file path
Base email layout	`resources/views/layouts/email.blade.php`
New ticket / auto-reply	`resources/views/emails/customer/created.blade.php`
Operator reply	`resources/views/emails/customer/reply.blade.php`
Ticket closed / notification	`resources/views/emails/customer/closed.blade.php`

Run this on the instance to see the exact file tree for your version:

ssh -i /tmp/lightsail_us_east_1.pem \
  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  admin@54.146.13.200 \
  "find /var/www/html/freescout/resources/views/emails -type f | sort"

Durability: will templates survive a FreeScout update?

Short answer: no — core file edits are overwritten by git pull. This is the key risk.

Options, in order of preference:

FreeScout Customization module (paid, terraform/freescout/modules.tf includes it): If the installed Customization module supports template-from-disk overrides, place branded templates in the module's override directory (check the module's documentation after install). This survives core updates.
FreeScout theme override path: Some FreeScout versions support a resources/views/vendor/ override path where Blade templates take precedence over core. Check whether this path exists on your installed version — if so, place templates there rather than editing core files.
Core file edit + post-update restore script: If neither of the above is available, maintain the branded templates in this repo at freescout/templates/ and re-apply them after each FreeScout git pull using the restore procedure below. Tag each FreeScout update as a trigger to re-verify templates.

Current status (as of 2026-05-04): The Customization module is declared in terraform/freescout/modules.tf. Once that module is active and its template-override path is confirmed, update this runbook with the correct target directory. Until then, deploy to core paths and re-apply after updates.

Deployment procedure

Step 1: SSH to the instance

ssh -i /tmp/lightsail_us_east_1.pem \
  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  admin@54.146.13.200

Step 2: Back up existing templates

sudo cp -r /var/www/html/freescout/resources/views/emails \
  /var/www/html/freescout/resources/views/emails.bak-$(date -u +%Y%m%d)

Step 3: Identify exact template file paths

find /var/www/html/freescout/resources/views/emails -type f | sort
find /var/www/html/freescout/resources/views/layouts -type f | sort

Confirm which files control: (a) the email layout wrapper, (b) the auto-reply, (c) the operator reply, (d) the closed/notification email.

Step 4: Transfer templates from the repo

From your local machine (with the repo checked out):

# SCP the HTML templates to the instance
scp -i /tmp/lightsail_us_east_1.pem \
  -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
  freescout/templates/autoreply.html \
  freescout/templates/operator-reply.html \
  freescout/templates/notification.html \
  admin@54.146.13.200:/tmp/

Step 5: Place templates at the correct Blade paths

On the instance, adapt the HTML content into the Blade template format. The HTML files in this repo are the canonical source of truth for brand design + copy. You must replace the {{variable}} placeholders with the correct Blade syntax for your FreeScout version (see variable reference above).

For the base email layout (if overriding the wrapper):

sudo cp /tmp/autoreply.html \
  /var/www/html/freescout/resources/views/emails/customer/created.blade.php

Repeat for each template type, mapping to the correct Blade file path.

Ensure correct ownership:

sudo chown -R www-data:www-data /var/www/html/freescout/resources/views/emails/

Step 6: Clear the view cache

cd /var/www/html/freescout
sudo -u www-data /usr/bin/php artisan view:clear
sudo -u www-data /usr/bin/php artisan config:cache

Step 7: Set auto-reply text via FreeScout UI

FreeScout has a UI-based auto-reply text field under Settings > Mailboxes > [mailbox] > Auto Reply. This controls the plain-text acknowledgment independently of the Blade HTML template.

Log in to https://tickets.raxx.app
Go to Settings (gear icon)
Click Mailboxes
Click Raxx Support (or support@raxx.app)
Click the Auto Reply tab
Paste the content of freescout/templates/autoreply.txt
Set the subject line to: Re: {conversation_subject} — Got it (verify the exact FreeScout variable name for conversation subject in your version)
Enable auto-reply if not already enabled
Verify "Do not auto-reply to auto-submitted messages" is enabled (prevents mail loops)
Click Save

Step 8: Test

From an external email address (not kris@moosequest.net if CF Access blocks the reply path), send one email to support@raxx.app. Confirm:

Auto-reply arrives within 2 minutes from no-reply@raxx.app
HTML auto-reply renders: Raxx wordmark visible in header, moss accent bar, correct footer
View HTML source: search for "FreeScout" — must return zero results
Background color in email body area matches #f8f5f0 (snow) or #ffffff (card)

Send a test operator reply from within FreeScout admin:

Open the test ticket
Write a reply and send it to the customer email
Confirm: Raxx wordmark in header, reply body in moss-bordered quote block, CTA button visible, footer correct

Step 9: Document any deviation

If the actual Blade file paths differ from those in this runbook, update the table in the "How FreeScout email templates work" section above. The next operator should not have to re-discover the paths.

Reverting to previous templates

# On the instance:
sudo cp -r /var/www/html/freescout/resources/views/emails.bak-YYYYMMDD \
  /var/www/html/freescout/resources/views/emails
sudo chown -R www-data:www-data /var/www/html/freescout/resources/views/emails/
cd /var/www/html/freescout
sudo -u www-data /usr/bin/php artisan view:clear

After a FreeScout core update

After running git pull in /var/www/html/freescout on the instance, re-apply templates:

Check whether the Customization module's override path now exists — if so, migrate to it.
If still editing core files, repeat Steps 4–7 above.
Run view cache clear (Step 6).
Run the test in Step 8.
Update the Last updated date at the top of this runbook.

Issue: #712 (parent card)
Epic: #707 (FreeScout productionization)
Triage notes: docs/ops/triage/2026-05-02-freescout-polish-sprint.md
Copy + legal: docs/marketing/2026-05-04-support-autoreply-copy.md
Legal posture: docs/business/2026-05-04-support-autoreply-legal-posture.md
FreeScout main runbook: docs/ops/runbooks/freescout.md
Template source files: freescout/templates/

Auto-generated from docs/ in raxx-app/TradeMasterAPI. Gated behind Cloudflare Access. Re-deployed on every push to main.