Email Templates & Themes

FleetQ includes a full email template system for outbound email delivery. Themes define the visual branding applied to every email your team sends. Templates define the content and structure — with dynamic variables that are substituted at send time. Both resources are team-scoped and fully manageable via the UI, API, or MCP tools.

Scenario: A growth team creates a "Company Brand" theme with their primary colour and logo. They then author a "Weekly Digest" template that references {{ $agent.name }} and {{ $signal.title }}. Each Friday, the "Weekly Report" experiment renders the template with live data and delivers it via the SMTP outbound connector.

Email Themes

A theme defines the visual styling that wraps every email template: colours, fonts, logo, and footer copy. Assign one theme to many templates to keep branding consistent across all outbound communications.

Field	Description
name	Human-readable label for the theme (e.g. "Company Brand", "Dark Mode").
description	Optional free-text description of when/how the theme should be used.
primary_color	Hex colour used for buttons, headings, and accent elements (e.g. `#3B82F6`).
secondary_color	Hex colour for secondary elements such as borders and muted backgrounds.
logo_url	Publicly accessible URL to the logo image rendered in the email header.
footer_text	Plain-text or minimal HTML displayed in every email footer (company name, unsubscribe notice, address).

Create a theme per brand or environment (e.g. "Production", "Staging") so all emails rendered in that context share a consistent look without any per-template configuration.

Email Templates

Templates define the subject line, HTML body, and metadata for a reusable email. They reference a theme for visual styling and declare dynamic variables that are substituted at delivery time.

Field	Description
name	Internal name for the template (e.g. "Weekly Digest", "Alert: Experiment Failed").
subject	Email subject line. Supports variable interpolation — e.g. `{{ $signal.title }}`.
body	Full HTML body with optional dynamic variable placeholders. AI-generated templates produce production-ready HTML.
theme_id	UUID of the email theme to apply. The theme's colours and logo are injected into the rendered output.
category	One of: `notification`, `digest`, `alert`, `report`, `custom`.

Dynamic variables

Templates support Blade-style double-curly-brace variables. At delivery time, FleetQ substitutes real values from the experiment run or outbound payload. Common variables include:

Variable	Resolves to
{{ $signal.title }}	Title of the inbound signal that triggered the run.
{{ $agent.name }}	Display name of the agent that produced the output.
{{ $experiment.title }}	Title of the parent experiment.
{{ $output }}	Raw text output from the last completed pipeline stage.
{{ $team.name }}	Name of the team sending the email.

Variable substitution uses simple string replacement. Undefined variables render as an empty string rather than causing a delivery failure.

Template categories

Category	Typical use
notification	Single-event alerts triggered immediately by agent output or state changes.
digest	Periodic summaries (daily, weekly) that batch multiple signals or results.
alert	High-priority messages for failures, budget overruns, or SLA breaches.
report	Structured outputs sent at the end of a project run or experiment.
custom	Anything that doesn't fit the above — promotional, transactional, etc.

MJML rendering microservice

Email templates can be authored in MJML — a responsive email markup language that compiles to inlined, table-based HTML compatible with every mail client. FleetQ ships an MJML rendering microservice as a Docker sidecar so you never need to install the MJML CLI or Node.js on the application container.

Component	Details
Docker service	`docker/mjml/` — a tiny Node.js container running the MJML HTTP API.
Service URL	MJML_SERVER_URL=http://mjml:15500
Renderer class	`MjmlRenderer` posts template bodies to the sidecar and returns the compiled HTML. Falls back to a plain-HTML pass-through when the service is unreachable.

Write your template body with MJML tags (<mj-section>, <mj-button>, …) and FleetQ compiles to bulletproof HTML at send time. The AI generator (below) can also produce MJML directly if you ask for it.

AI template generation

FleetQ can generate a complete, professionally styled HTML email template from a plain-text prompt. The AI matches the structure and tone you describe, embeds your theme colours, and outputs clean HTML that is ready to send. Use the email_template_generate MCP tool or the REST API endpoint.

bash

# Generate a template via MCP (stdio or HTTP)
email_template_generate({
  "template_id": "018f1a2b-...",
  "prompt": "Write a weekly digest email that summarises the top 3 signals processed this week. Include a clear CTA to view the full report in FleetQ."
})

bash

# Generate via REST API
curl -X POST https://your-instance.example/api/v1/email-templates/{id}/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a weekly digest email that summarises the top 3 signals processed this week."}'

Describe the purpose and audience of the email in your prompt for best results. For example: "Professional alert email for a DevOps team notifying them that an experiment has failed, including the experiment name and a link to the failure log."

The FleetQ assistant can also generate full email themes (not just templates) via the email_theme_create tool. Ask it to "create a dark-mode theme for our Acme product" and it will pick a cohesive colour palette, drop in the logo, and craft a footer — all in one turn.

Using templates with outbound delivery

Email templates are consumed by outbound email connectors (SMTP Email, Email). When an experiment stage or workflow node produces an outbound proposal, it references a template by ID and passes a data payload for variable substitution. FleetQ renders the template, injects theme styling, and delivers the final HTML via the configured connector.

The typical flow is:

Create a theme and one or more templates in Settings → Email or via the API.
Configure an SMTP Email or Email outbound connector, pointing it at your template.
In your experiment or workflow, add an outbound step that targets the connector and supplies data variables.
When the step executes, FleetQ substitutes variables, wraps the body with the theme, and delivers the email.

Each outbound delivery is recorded as an OutboundAction with status, timestamps, and the rendered subject/body. You can inspect these in the Experiment detail → Outbound tab.

MCP tools

All email theme and template operations are available as MCP tools, giving AI agents full programmatic access without needing the REST API.

Theme tools

Tool	Description
email_theme_list	List all email themes for the current team.
email_theme_get	Retrieve a single theme by ID, including all styling fields.
email_theme_create	Create a new theme with name, colours, logo URL, and footer text.
email_theme_update	Update any fields on an existing theme.
email_theme_delete	Delete a theme. Templates referencing it will lose their theme association.

Template tools

Tool	Description
email_template_list	List all templates, optionally filtered by category.
email_template_get	Retrieve a single template including its full HTML body.
email_template_create	Create a template with name, subject, body, theme reference, and category.
email_template_update	Update any field on an existing template.
email_template_delete	Delete a template permanently.
email_template_generate	Generate professional HTML content for an existing template from a plain-text prompt using AI.

API endpoints

All endpoints require a Sanctum bearer token and respect team scoping. Full schema is available at /docs/api (OpenAPI 3.1).

Email Themes — `/api/v1/email-themes`

Method & Path	Purpose
GET /api/v1/email-themes	List all themes (cursor-paginated).
GET /api/v1/email-themes/{id}	Retrieve a single theme.
POST /api/v1/email-themes	Create a new theme.
PUT /api/v1/email-themes/{id}	Update an existing theme.
DELETE /api/v1/email-themes/{id}	Delete a theme.

Email Templates — `/api/v1/email-templates`

Method & Path	Purpose
GET /api/v1/email-templates	List all templates, optionally filtered by `category`.
GET /api/v1/email-templates/{id}	Retrieve a single template including HTML body.
POST /api/v1/email-templates	Create a new template.
PUT /api/v1/email-templates/{id}	Update an existing template.
DELETE /api/v1/email-templates/{id}	Delete a template.
POST /api/v1/email-templates/{id}/generate	Generate AI-produced HTML content for the template. Body: `{"prompt": "..."}`.

Explore the interactive API schema at /docs/api to try endpoints directly against your running instance with your bearer token.