SapaganDocs sapagan.com

API reference

Push templates

Reusable push messages with Liquid, and their previews.

Reusable push messages with Liquid, and their previews.

GET /v1/templates#

List templates

A workspace key lists every template (filter with scopeId, or none for workspace-owned ones); a scope credential lists its own scope's only.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
scopeIdquerystring (uuid) or "none"
channelquery"push" | "email"
purposequery"marketing" | "transactional"
includeArchivedquery"true" | "false"
afterquerystring (uuid)
limitqueryinteger
curl -X GET "$SAPAGAN_URL/v1/templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK. Errors use the error body.

Example response 200

{
  "templates": [
    {
      "id": "user-42",
      "scopeId": "<scopeId>",
      "channel": "<channel>",
      "purpose": "marketing",
      "ttlMinutes": 1,
      "name": "order_placed",
      "content": null,
      "layoutId": "<layoutId>",
      "layoutVersion": 1,
      "version": 1,
      "contentUpdatedAt": "<contentUpdatedAt>",
      "createdBy": "<createdBy>",
      "createdVia": "<createdVia>",
      "createdAt": "<createdAt>",
      "updatedAt": "<updatedAt>",
      "archivedAt": "<archivedAt>"
    }
  ],
  "next": "<next>"
}

POST /v1/templates#

Create a template

A scope credential creates templates in its own scope only (scopeId omitted or its own; another scope is 404). A workspace key may create a workspace-owned template (omit scopeId) or one for a scope. Push content is {title, body, imageUrl?, destination}; title and body are Liquid.

Accepted keys Server key Store key Store token

Request body

FieldTypeNotes
scopeIdstring (uuid) or null
channel required"push" | "email"
purpose"marketing" | "transactional"
ttlMinutesintegermin 1, max 1440
name requiredstringmin 1, max 200
contentany
layoutIdstring (uuid) or null
curl -X POST "$SAPAGAN_URL/v1/templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "push",
    "name": "order_placed"
  }'

Responses

201 Created, 400 Invalid request, 404 Not found. Errors use the error body.

Example response 201

{
  "id": "user-42",
  "scopeId": "<scopeId>",
  "channel": "<channel>",
  "purpose": "marketing",
  "ttlMinutes": 1,
  "name": "order_placed",
  "content": null,
  "layoutId": "<layoutId>",
  "layoutVersion": 1,
  "version": 1,
  "contentUpdatedAt": "<contentUpdatedAt>",
  "createdBy": "<createdBy>",
  "createdVia": "<createdVia>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>",
  "archivedAt": "<archivedAt>"
}

GET /v1/templates/{id}#

Read a template

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 404 Not found. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "scopeId": "<scopeId>",
  "channel": "<channel>",
  "purpose": "marketing",
  "ttlMinutes": 1,
  "name": "order_placed",
  "content": null,
  "layoutId": "<layoutId>",
  "layoutVersion": 1,
  "version": 1,
  "contentUpdatedAt": "<contentUpdatedAt>",
  "createdBy": "<createdBy>",
  "createdVia": "<createdVia>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>",
  "archivedAt": "<archivedAt>"
}

PATCH /v1/templates/{id}#

Update a template

Changing content raises version and contentUpdatedAt (a broadcast keeps the snapshot of content it was given; to use the new content, PATCH the broadcast with this templateId, which is an edit and needs approval again, P1-06). archived: true archives, false restores. The channel and owner never change.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 200
contentany
layoutIdstring (uuid) or null
archivedboolean
curl -X PATCH "$SAPAGAN_URL/v1/templates/user-42" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_placed",
    "content": null,
    "layoutId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "archived": true
  }'

Responses

200 OK, 400 Invalid request, 404 Not found. Errors use the error body.

Example response 200

{
  "id": "user-42",
  "scopeId": "<scopeId>",
  "channel": "<channel>",
  "purpose": "marketing",
  "ttlMinutes": 1,
  "name": "order_placed",
  "content": null,
  "layoutId": "<layoutId>",
  "layoutVersion": 1,
  "version": 1,
  "contentUpdatedAt": "<contentUpdatedAt>",
  "createdBy": "<createdBy>",
  "createdVia": "<createdVia>",
  "createdAt": "<createdAt>",
  "updatedAt": "<updatedAt>",
  "archivedAt": "<archivedAt>"
}

POST /v1/templates/{id}/test#

Send a test of an email template

Renders the stored email template with sample data and sends it to to, which must be one of the workspace's test addresses (PUT /v1/workspace/email-settings, owner). The subject starts with [Tes]; the footer's links open the preference center's neutral page. Limited per store (the workspace's own templates: per workspace) and per template, counted before the address is checked; a refused address is 403 test_send_refused, a suppressed one (a bounce or a complaint) 409 suppressed_address. Nothing is stored.

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
tostringmax 254
sampleobject
sample.customerobject
sample.eventobject
sample.deliveryobject
sample.scopeobject
curl -X POST "$SAPAGAN_URL/v1/templates/user-42/test" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "<to>",
    "sample": {
      "customer": {},
      "event": {},
      "delivery": {},
      "scope": {}
    }
  }'

Responses

202 Accepted, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict, 429 Rate limited, 502 Send failed, 503 Unavailable. Errors use the error body.

Example response 202

{
  "sent": true,
  "providerMessageId": "<providerMessageId>",
  "subject": "<subject>"
}

POST /v1/templates/preview#

Preview a template

Renders a stored template (templateId) or inline content against sample data. A render problem is valid: false with errors, not an HTTP error. warnings carry text over a platform's limit with the truncated text. Nothing is stored.

Accepted keys Server key Store key Store token

Request body

FieldTypeNotes
templateIdstring (uuid)
channel"push" | "email"
contentany
storeSlugstringmax 100
layoutIdstring (uuid) or null
sampleobject
sample.customerobject
sample.eventobject
sample.deliveryobject
sample.scopeobject
curl -X POST "$SAPAGAN_URL/v1/templates/preview" \
  -H "Authorization: Bearer $SAPAGAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
    "channel": "push",
    "content": null,
    "storeSlug": "<storeSlug>"
  }'

Responses

200 OK, 400 Invalid request, 404 Not found. Errors use the error body.

Example response 200

{
  "valid": true,
  "errors": [
    {
      "field": "<field>",
      "code": "<code>",
      "message": "<message>",
      "line": 1
    }
  ],
  "warnings": [
    {
      "code": "<code>",
      "field": "<field>",
      "platform": "<platform>",
      "limit": 1,
      "length": 1,
      "truncatedText": "<truncatedText>"
    }
  ],
  "rendered": {
    "title": "Pesanan dikirim",
    "body": "Pesanan #1042 sedang dalam perjalanan.",
    "imageUrl": "<imageUrl>",
    "link": "<link>",
    "type": "<type>"
  },
  "email": {
    "subject": "<subject>",
    "preheader": "<preheader>",
    "html": "<html>",
    "text": "<text>",
    "links": [
      "<links>"
    ],
    "sizeBytes": 1
  },
  "emailWarnings": [
    {
      "field": "<field>",
      "code": "<code>",
      "message": "<message>"
    }
  ]
}