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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
scopeId | query | string (uuid) or "none" | |
channel | query | "push" | "email" | |
purpose | query | "marketing" | "transactional" | |
includeArchived | query | "true" | "false" | |
after | query | string (uuid) | |
limit | query | integer |
curl -X GET "$SAPAGAN_URL/v1/templates" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"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.
Request body
| Field | Type | Notes |
|---|---|---|
scopeId | string (uuid) or null | |
channel required | "push" | "email" | |
purpose | "marketing" | "transactional" | |
ttlMinutes | integer | min 1, max 1440 |
name required | string | min 1, max 200 |
content | any | |
layoutId | string (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"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"channel": "push",
"name": "order_placed"
}),
});
const data = await res.json();Responses
{
"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
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 200 |
content | any | |
layoutId | string (uuid) or null | |
archived | boolean |
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
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"content": null,
"layoutId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"archived": true
}),
});
const data = await res.json();Responses
{
"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.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
to | string | max 254 |
sample | object | |
sample.customer | object | |
sample.event | object | |
sample.delivery | object | |
sample.scope | object |
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": {}
}
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates/user-42/test`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"to": "<to>",
"sample": {
"customer": {},
"event": {},
"delivery": {},
"scope": {}
}
}),
});
const data = await res.json();Responses
{
"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.
Request body
| Field | Type | Notes |
|---|---|---|
templateId | string (uuid) | |
channel | "push" | "email" | |
content | any | |
storeSlug | string | max 100 |
layoutId | string (uuid) or null | |
sample | object | |
sample.customer | object | |
sample.event | object | |
sample.delivery | object | |
sample.scope | object |
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>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/templates/preview`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"templateId": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b",
"channel": "push",
"content": null,
"storeSlug": "<storeSlug>"
}),
});
const data = await res.json();Responses
{
"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>"
}
]
}