Email Templates

Templates are reusable, variable-driven email written in Jinja2 — a signature, a branded header, a layout wrapper, or a complete email. Define a template once, attach it as a mailbox's default, and every outgoing message from that mailbox is consistently formatted without you re-pasting boilerplate.

Templates render in a Jinja2 sandbox (SandboxedEnvironment), so untrusted variable data cannot break out into arbitrary code execution.

Template types

The template_type says where the template applies:

::table
Type | What it is | Typical use
signature | A block appended to the body | Professional sign-offs
header | A block prepended to the body | Branded headers
layout | A wrapper with a {{ body }} slot | Full email structure around your text
full | A complete standalone email | Marketing / lifecycle emails

Create a template

POST /mail/templates creates one. The html_source is your Jinja2 markup; variables in {{ … }} are auto-detected if you do not list them.

curl -X POST "https://spideriq.ai/api/v1/mail/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sales-signature",
    "template_type": "signature",
    "html_source": "<hr><p style=\"margin:0;font-weight:bold\">{{ sender_name }}</p><p style=\"margin:0;color:#666\">{{ title }} | {{ company }}</p>"
  }'

The fields:

• name (required) — unique per workspace; letters, numbers, hyphens, and underscores only (lowercased).

• template_type (default full) — one of the types above.

• html_source (required) — the Jinja2 HTML.

• text_source (optional) — a plain-text version.

• variables (optional) — auto-detected from the source if omitted.

• is_default (optional) — mark as the default for its type.

Manage templates with GET /mail/templates (optionally ?template_type=), GET /mail/templates/{id}, PATCH /mail/templates/{id}, and DELETE /mail/templates/{id} (a soft delete — sets the template inactive).

Preview with sample data

Before relying on a template, render it with sample values via POST /mail/templates/{id}/preview:

curl -X POST "https://spideriq.ai/api/v1/mail/templates/42/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "variables": { "sender_name": "Alice Smith", "title": "Sales Director", "company": "Acme" } }'
# → { "rendered_html": "...", "variables_used": [...], "missing_variables": [] }

The response shows the rendered HTML, which variables were used, and any that were missing — so you can catch a typo before it reaches a recipient.

Note: The preview body accepts the values under either variables (current) or template_data (legacy, kept for older callers). Both mean the same thing; use variables.

Apply a template by default per mailbox

The supported way to apply a template to outgoing mail is to set it as a mailbox default. Every message sent from that mailbox is then formatted with it, and template_variables fills the placeholders. Set it via the mailbox update endpoint:

curl -X PATCH "https://spideriq.ai/api/v1/mail/mailboxes/alice@yourcompany.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_template_id": 42,
    "template_variables": { "sender_name": "Alice Smith", "title": "Sales Director", "company": "Acme" }
  }'

Clear a mailbox's default by setting default_template_id to 0.

Tip: A signature or header template plus mailbox-level template_variables gives every agent send a consistent sign-off with zero per-message effort — set it once when you connect the mailbox.

Next steps

1. Set the mailbox default you just created.

2. Send an email and confirm the template renders.

3. Template endpoints in the API Reference.