Templates API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The Templates API manages email, notification and intervention templates and FAQs (both stored as templates, distinguished by type), renders a template against data, and stores template images. Every endpoint runs as the token’s owner and is gated by the templates ability plus the owner’s admin role. Stock responses are managed through the Settings API. For how templates are written and the placeholders they take, see Templates.

Abilities and conventions

1. templates:read — read and render endpoints.
2. templates:write — create / update / delete and image upload. Write implies read.

All endpoints are POST and JSON, except the image upload, which is multipart. A template’s type is email, notification, intervention or faq. A refusal is a 422 with a message naming the problem:

{
  "ok": false,
  "error": "validation_failed",
  "message": "A template with this identifier already exists for this type."
}

Endpoints

Reading and searching

1. templates lists each template’s id, type, identifier, subject and keywords; templates/faqs lists each FAQ’s id, identifier, subject (the question) and ordinal.
2. templates/show returns the full record for a template_id, with inline images embedded in content as data: URIs and localisations listing its language variants.
3. templates/search matches search against the identifier, subject, content and keywords; every word must match, and "quoted phrases" match as a whole. mode scopes the types searched — templates (the default), faq or stock — and type narrows to one type.

Creating

templates/create stores every field given:

1. type — required.
2. identifier — required, and unique within its type. An FAQ is given its identifier automatically.
3. subject, content (Quill HTML), description, legend, keywords (comma- or newline-separated), public_route and auth_route.
4. is_enabled — defaults to true; send false to create a disabled draft.
5. ordinal — an FAQ’s position in the list.

Images pasted into content as data: URIs are stored as the template’s own images and referenced by cid:. The reply carries the new template.

Updating

templates/update takes a template object holding the template’s id and only the fields to change; every field left out keeps its value. An FAQ’s identifier is fixed once it is created.

{
  "template": {
    "id": 99,
    "subject": "Your order {{order_number}} is on its way"
  }
}

The reply carries the template’s identifier. For email, notification and FAQ templates it also lists the localisations, and when the English text changed, stale_localisations names the language variants written against the previous text.

Limits

The identifier, subject, keywords, description, legend, public_route and auth_route fields are limited to 255 characters each; content has no such limit. A longer value is refused with 422 and a message such as Description is 300 characters; the limit is 255., and nothing is saved.

Rendering without sending

templates/render fills a template with data and returns the result, sending nothing — use it to check a template’s output before it goes to a customer. It takes template_identifier and data (both required) and type (default email).

{
  "template_identifier": "order_dispatched",
  "data": { "name": "Marcus", "order_number": "TB-10442" }
}

The reply holds the rendered subject and content, with inline images embedded as data: URIs:

{
  "ok": true,
  "template_id": 99,
  "subject": "Your order TB-10442 is on its way",
  "content": "<p>Hi Marcus, ...</p>"
}

An identifier with no template of that type is refused with 422. To send a rendered email template, use mail/send.

Images

To add an image to a template or FAQ, upload it to templates/image-upload as multipart form data with template_id and file. The reply gives the image’s cid, sha256, mime_type and an img tag (<img src="cid:...">) to place in the content with an update. A file that is not an image is refused with 422.

curl -X POST https://support.sole-trader.example/api/v1/templates/image-upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F template_id=99 \
  -F [email protected]

A template’s cid: images are embedded in every email sent from it, so they display in the recipient’s mail client.