Raxx · internal docs

internal · gated

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:

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.218 on raxx-tickets — confirmed 2026-06-19):

Template type Actual file path Notes
Auto-reply (new ticket acknowledgment) resources/views/emails/customer/auto_reply.blade.php Sends when customer emails support@raxx.app
Operator reply (agent reply to customer) resources/views/emails/customer/reply_fancy.blade.php Threaded HTML reply to customer
Auto-reply plaintext resources/views/emails/customer/auto_reply_text.blade.php Plaintext fallback
Operator reply plaintext resources/views/emails/customer/reply_fancy_text.blade.php Plaintext fallback

Note: The paths created.blade.php, reply.blade.php, closed.blade.php referenced in older FreeScout docs do NOT exist in 1.8.218. The actual customer-facing templates are auto_reply.blade.php and reply_fancy.blade.php. The spec's vendor:publish --tag=freescout-views approach also does NOT apply — there is no freescout-views tag registered on this install. Edit core files directly and re-apply after git pull.

Branded Blade versions of the deployed templates are tracked at freescout/templates/blade/ in the repo. Re-apply them after any FreeScout core git pull.

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:

  1. 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.

  2. 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.

  3. 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.

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

Send a test operator reply from within FreeScout admin:

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:

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