Email Templates

Use email-templates to manage per-user and per-genie email template configurations. Templates control the layout and content of outgoing emails such as conversation reports.

Standard users manage their own templates. Admin users can read or write templates for any user by passing adminMode: true and the target userId. Team members write to the team owner’s templates by default; pass personal: true to write to your own account instead.

Get effective config

Returns the resolved template configuration for a given type. Looks up in priority order: genie-specific template → user-level template → system default. Returns null if no configuration exists at any level.

string

required

Must be "email-templates"

string

required

Must be "getConfig"

object

required

Show properties

string

required

Template type identifier (for example "report").

string

Genie UUID. When provided, a genie-specific template is checked first before falling back to the user-level template.

string

Admin only. Resolve the config for this user ID instead of the authenticated user.

boolean

Admin only. Must be true to use the userId parameter.

boolean

Whether the request succeeded.

object

Show properties

object | null

The resolved template configuration object, or null if no template is configured at any level.

const response = await ApiService.invoke("email-templates", "getConfig", undefined, {
  type: "report",
  agent_id: "550e8400-e29b-41d4-a716-446655440000",
});
const config = response?.config;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "getConfig",
    "data": {
      "type": "report",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

{
  "success": true,
  "data": {
    "config": {
      "subject": "Your conversation summary",
      "headerColor": "#4E9CFF",
      "logoUrl": "https://storage.example.com/logo.png"
    }
  }
}

List templates

Returns a paginated list of email templates for the authenticated user, optionally filtered by type or genie.

string

required

Must be "email-templates"

string

required

Must be "list" or "all" (both return the same result).

object

Show properties

number

default:"50"

Results per page. Maximum 500.

number

default:"0"

Number of results to skip.

string

Filter by template type.

string

Filter by genie UUID. Pass null to return only templates with no genie association.

string

Admin only. List templates for this user ID. Also accepted as impersonatedUserId.

string

Admin only. Alias for userId.

boolean

Admin only. Must be true to use the userId / impersonatedUserId parameter.

boolean

object

Show properties

array

Show item properties

string

Template UUID.

string

Owner user ID.

string | null

Genie UUID this template is scoped to, or null for a user-level template.

string | null

Genie display name, if agent_id is set.

string

Template type identifier.

object

Template configuration object.

boolean

Whether this is a system-default template.

string

ISO 8601 creation timestamp.

number

Total matching templates.

number

Applied limit.

number

Applied offset.

const response = await ApiService.invoke("email-templates", "list", undefined, {
  limit: 50,
  offset: 0,
  type: "report",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "list",
    "data": { "limit": 50, "offset": 0, "type": "report" }
  }'

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "tpl-uuid-123",
        "user_id": "usr-uuid-456",
        "agent_id": null,
        "agent_name": null,
        "type": "report",
        "config": { "subject": "Your conversation summary" },
        "is_default": false,
        "created_at": "2024-01-15T10:30:00.000Z"
      }
    ],
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Get template

Retrieves a single email template by ID.

string

required

Must be "email-templates"

string

required

Must be "get"

string

required

The template UUID.

boolean

object

Show properties

object

The full template object. Same shape as list items above, plus an embedded agent object when agent_id is set.

const response = await ApiService.invoke("email-templates", "get", "tpl-uuid-123");
const template = response?.template;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "get",
    "id": "tpl-uuid-123"
  }'

Create template

Creates a new email template record.

string

required

Must be "email-templates"

string

required

Must be "create"

object

required

Show properties

string

required

Template type identifier.

object

required

Template configuration object.

string

Genie UUID. When provided, the template is scoped to that genie only.

boolean

default:"false"

Whether to mark this as a default template.

boolean

default:"false"

Team members only. Pass true to create the template under your own account instead of the team owner’s account.

boolean

object

Show properties

object

The newly created template.

const response = await ApiService.invoke("email-templates", "create", undefined, {
  type: "report",
  config: { subject: "Custom report subject" },
  agent_id: "550e8400-e29b-41d4-a716-446655440000",
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "create",
    "data": {
      "type": "report",
      "config": { "subject": "Custom report subject" },
      "agent_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }'

{
  "success": true,
  "data": {
    "template": {
      "id": "tpl-new-uuid",
      "user_id": "usr-uuid-456",
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "report",
      "config": { "subject": "Custom report subject" },
      "is_default": false,
      "created_at": "2024-01-15T11:00:00.000Z"
    }
  }
}

Update template

Upserts a template identified by type and optionally agent_id. If a matching template already exists it is updated; otherwise a new one is created. Use create when you need the returned template object — update only returns the ID.

string

required

Must be "email-templates"

string

required

Must be "update"

object

required

Show properties

string

required

Template type identifier.

object

required

Replacement configuration. The entire config is replaced, not merged.

string

Genie UUID. Scopes the upsert to a genie-specific template. Omit to target the user-level template for this type.

string

Admin only. Write the template for this user ID. Also accepted as impersonatedUserId.

string

Admin only. Alias for userId.

boolean

Admin only. Must be true to use the userId / impersonatedUserId parameter.

boolean

default:"false"

Team members only. Pass true to write to your own account instead of the team owner’s account.

boolean

object

Show properties

string | number

ID of the updated or created template.

const response = await ApiService.invoke("email-templates", "update", undefined, {
  type: "report",
  config: { subject: "Updated subject line" },
});

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "update",
    "data": {
      "type": "report",
      "config": { "subject": "Updated subject line" }
    }
  }'

{
  "success": true,
  "data": { "id": "tpl-uuid-123" }
}

Delete template

Permanently deletes an email template by ID.

string

required

Must be "email-templates"

string

required

Must be "delete"

string

required

The template UUID to delete.

boolean

object

Show properties

boolean

const response = await ApiService.invoke("email-templates", "delete", "tpl-uuid-123");

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "delete",
    "id": "tpl-uuid-123"
  }'

Clone default template

Copies the system-default template of a given type into the user’s account. If the user already has a template of that type, its config is replaced with the default. Returns the cloned config.

string

required

Must be "email-templates"

string

required

Must be "cloneDefault"

object

required

Show properties

string

required

Template type to clone the default for.

string

Genie UUID. When provided, the clone is scoped to that genie.

boolean

default:"false"

Team members only. Pass true to clone into your own account rather than the team owner’s account.

boolean

object

Show properties

object

The config copied from the system default.

const response = await ApiService.invoke("email-templates", "cloneDefault", undefined, {
  type: "report",
});
const config = response?.config;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "cloneDefault",
    "data": { "type": "report" }
  }'

Copy logo

Copies a logo image from an external storage location into HelpGenie-managed storage and returns the new URL. If the image is already in internal storage or the copy fails, the original URL is returned unchanged.

string

required

Must be "email-templates"

string

required

Must be "copyLogo"

object

required

Show properties

string

required

Public URL of the logo to copy.

boolean

object

Show properties

string

The new internal URL, or the original URL if the copy was skipped or failed.

Sync signature visibility

Propagates a genie’s signature enabled/disabled setting across its email template rows. For existing per-type rows the signature block is toggled in place ("patched"); rows that don’t yet exist are left alone ("no_template") — per-type rows are never force-created. The genie’s shared brand template (the type: null fallback used when no per-type override exists) is also patched when it exists; if it is absent and the genie has branding configured, a new brand template row is created with the signature block set accordingly ("forked"). Templates for other genies are never touched.

string

required

Must be "email-templates"

string

required

Must be "sync-signature-enabled"

object

required

Show properties

string

required

Genie UUID whose signature visibility should be synced across all template types.

boolean

required

true to enable the email signature block; false to disable it.

boolean

default:"false"

Team members only. Pass true to write forked templates to your own account instead of the team owner’s account.

boolean

object

Show properties

object

A map of outcome strings keyed by template scope. Keys are "brand" (the genie’s shared type: null brand template) and each per-type identifier: "conversation_report", "customer_report", "meeting_recap", "escalation_alert", "conversation_digest", "conversation_auto_digest", "view_report". Each value is one of:

Value	Meaning
`"patched"`	An existing template row was updated in place.
`"forked"`	No brand template row existed; one was created from the genie’s branding. Only possible for the `"brand"` key — per-type rows are never created by this action.
`"unchanged"`	The signature block was already in the requested state.
`"no_template"`	No template row exists for this scope (per-type rows are left as-is).

const response = await ApiService.invoke("email-templates", "sync-signature-enabled", undefined, {
  agent_id: "550e8400-e29b-41d4-a716-446655440000",
  enabled: true,
});
const { results } = response;

curl -X POST https://api.helpgenie.ai/v1 \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "email-templates",
    "action": "sync-signature-enabled",
    "data": {
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "enabled": true
    }
  }'

{
  "success": true,
  "data": {
    "results": {
      "brand": "forked",
      "conversation_report": "patched",
      "customer_report": "unchanged",
      "meeting_recap": "patched",
      "escalation_alert": "no_template",
      "conversation_digest": "no_template",
      "conversation_auto_digest": "unchanged",
      "view_report": "patched"
    }
  }
}

Error codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`FORBIDDEN`	403	User lacks permission for the operation
`NOT_FOUND`	404	Template not found
`VALIDATION_ERROR`	400	Missing required fields (`type`, `config`)
`INVALID_ACTION`	400	Unknown action
`INTERNAL_ERROR`	500	Server-side error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

Get effective config

List templates

Get template

Create template

Update template

Delete template

Clone default template

Copy logo

Sync signature visibility

Error codes

​Get effective config

​List templates

​Get template

​Create template

​Update template

​Delete template

​Clone default template

​Copy logo

​Sync signature visibility

​Error codes

Get effective config

List templates

Get template

Create template

Update template

Delete template

Clone default template

Copy logo

Sync signature visibility

Error codes