API reference
Email settings, layouts, templates, suppressions and deliverability.
Email settings, layouts, templates, suppressions and deliverability.
GET /v1/email-templates#
The organisation's saved rows and email templates, by name
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
kind | query | "row" | "email" |
curl -X GET "$SAPAGAN_URL/v1/email-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email-templates`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"templates": [
{
"id": "user-42",
"kind": "row",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}
]
}POST /v1/email-templates#
Save a row or an email for the organisation (operator)
kind: row takes a v2 row, kind: email a v2 email (version: 2). The engine checks it for this workspace (link allowlist, image hosts and own uploads, the footer rule; a new HTML block needs an owner): 400 invalid_content with details.issues. Names are unique per organisation and kind (409 name_taken). Every workspace of the organisation sees it. Audited.
Request body
| Field | Type | Notes |
|---|---|---|
kind required | "row" | "email" | |
name required | string | min 1, max 120 |
description | string | max 500 |
content required | object |
curl -X POST "$SAPAGAN_URL/v1/email-templates" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "row",
"name": "order_placed",
"content": {}
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email-templates`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"kind": "row",
"name": "order_placed",
"content": {}
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"kind": "row",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"content": {}
}GET /v1/email-templates/{id}#
One saved row or email template with its content
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/email-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email-templates/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"kind": "row",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>",
"content": {}
}PATCH /v1/email-templates/{id}#
Rename a saved row or email template, or change its description (operator)
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 120 |
description | string | max 500 |
curl -X PATCH "$SAPAGAN_URL/v1/email-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"description": "<description>"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email-templates/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"description": "<description>"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"kind": "row",
"name": "order_placed",
"description": "<description>",
"workspaceId": "<workspaceId>",
"createdBy": "<createdBy>",
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}DELETE /v1/email-templates/{id}#
Remove a saved row or email template (operator)
Emails already made with it are not affected. Audited, with the content it had.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X DELETE "$SAPAGAN_URL/v1/email-templates/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email-templates/user-42`, {
method: "DELETE",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"removed": true
}GET /v1/email/deliverability#
Email bounces and complaints, for the workspace and per store
Email deliveries created in the last hours (default 24, at most 720) as SES's feedback left them: hardBounced (permanent; the rate SES and store health judge), softBounced (transient, shown apart), accountSuppressed (refused by SES's account-level list), complained. Rates are of sent. Alerts go to the operators above 2 percent hard bounces or 0.08 percent complaints over 24 hours with at least 500 sends.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
hours | query | integer |
curl -X GET "$SAPAGAN_URL/v1/email/deliverability" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email/deliverability`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"hours": 1,
"workspace": {
"sent": 1,
"delivered": 1,
"hardBounced": 1,
"softBounced": 1,
"accountSuppressed": 1,
"complained": 1,
"hardBounceRate": 1,
"complaintRate": 1
},
"stores": [
{
"sent": 1,
"delivered": 1,
"hardBounced": 1,
"softBounced": 1,
"accountSuppressed": 1,
"complained": 1,
"hardBounceRate": 1,
"complaintRate": 1,
"scopeId": "<scopeId>",
"name": "order_placed"
}
]
}GET /v1/email/designer#
The email editor's context: workspace kind, footer and HTML block rights, starter gallery
curl -X GET "$SAPAGAN_URL/v1/email/designer" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/email/designer`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"marketplace": true,
"footerStyleAllowed": true,
"htmlBlockAllowed": true,
"starters": [
{
"key": "<key>",
"audience": "general",
"name": {
"id": "user-42",
"en": "<en>"
},
"description": {
"id": "user-42",
"en": "<en>"
},
"content": {
"id": {},
"en": {}
}
}
]
}GET /v1/layouts#
List email layouts
curl -X GET "$SAPAGAN_URL/v1/layouts" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/layouts`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"layouts": [
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"version": 1,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}
]
}POST /v1/layouts#
Create an email layout
MJML from the layout allowlist (no mj-raw, mj-style, mj-font or includes; links on the workspace's allowlist, images on the image hosts) with {{ content }} once and optionally {{ footer }}: the footer with the unsubscribe and preference links is added by Sapagan and cannot be written by a layout. locked: true lets stores' templates use it. Audited with reason.
Request body
| Field | Type | Notes |
|---|---|---|
name required | string | min 1, max 200 |
mjml required | string | min 1, max 100000 |
locked | boolean | default false |
reason required | string | min 3, max 2000 |
curl -X POST "$SAPAGAN_URL/v1/layouts" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"mjml": "<mjml>",
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/layouts`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"mjml": "<mjml>",
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"version": 1,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}GET /v1/layouts/{id}#
Read an email layout
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
curl -X GET "$SAPAGAN_URL/v1/layouts/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/layouts/user-42`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"version": 1,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}PATCH /v1/layouts/{id}#
Change an email layout
A changed mjml is checked like a new one; the database raises version and keeps the old one. A saved template keeps rendering the version it was saved with until it is saved again (which raises its own version, so it is reviewed again). reason is required and audited.
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
id | path | string required |
Request body
| Field | Type | Notes |
|---|---|---|
name | string | min 1, max 200 |
mjml | string | min 1, max 100000 |
locked | boolean | |
reason | string | max 2000 |
curl -X PATCH "$SAPAGAN_URL/v1/layouts/user-42" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/layouts/user-42`, {
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"id": "user-42",
"scopeId": "<scopeId>",
"name": "order_placed",
"mjml": "<mjml>",
"locked": true,
"version": 1,
"createdAt": "<createdAt>",
"updatedAt": "<updatedAt>"
}GET /v1/scope/email/starters#
The store's email starters (P2-10, Kontak email)
The email designer v2 gallery as a store's email may use it: the marketplace starters (Promo, Produk baru, Ajak kembali) and the general ones a store may send (Kosong, Terima kasih), in Bahasa Indonesia, as v2 content a store's email accepts (Toco destinations, the store's own variables, one or two columns, no settings). Product cards start with sample products, which a save refuses until the store's own are chosen. limits: the editor's block limits. Workspace credentials are 403; an own-brand workspace answers 404 like an unknown route.
curl -X GET "$SAPAGAN_URL/v1/scope/email/starters" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/scope/email/starters`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"starters": [
{
"key": "<key>",
"from": "general",
"name": "order_placed",
"description": "<description>",
"content": {}
}
],
"limits": {
"rows": 1,
"blocksPerColumn": 1,
"totalBlocks": 1
}
}GET /v1/suppressions#
Suppressed addresses (hard bounces, complaints, SES's account list), newest first
Addresses are masked (a***@example.com). address looks up one exact address and shows it whole. orgWide: suppressed in every workspace of the organisation (SES's account-level suppression list). Paged with cursor (the previous page's nextCursor).
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
channel | query | "email" | "push" | "inbox" | "webhook" | "whatsapp" | |
address | query | string | |
reason | query | "hard_bounce" | "complaint" | "account_suppressed" | "unsubscribe_all" | "manual" | "invalid_token" | |
limit | query | integer | |
cursor | query | string |
curl -X GET "$SAPAGAN_URL/v1/suppressions" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/suppressions`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"suppressions": [
{
"channel": "<channel>",
"address": "<address>",
"reason": "Checked with the owner",
"detail": "<detail>",
"orgWide": true,
"sourceDeliveryId": "<sourceDeliveryId>",
"createdAt": "<createdAt>"
}
],
"total": 1,
"nextCursor": "<nextCursor>"
}POST /v1/suppressions/remove#
Remove one suppression (owners in the console only; audited)
Only a person who owns the workspace, signed in to the console (a workspace key is 403 operator_required), with a reason of 3 to 500 characters. The address is sent again only if it is right: a hard bounce will bounce again, and SES's account list refuses it whatever Sapagan does. An orgWide suppression is removed in this workspace only. The database writes the audit row (suppression_remove, the address masked and hashed).
Request body
| Field | Type | Notes |
|---|---|---|
channel | "email" | "push" | "inbox" | "webhook" | "whatsapp" | default "email" |
address required | string | min 1, max 512 |
reason required | string | max 500 |
curl -X POST "$SAPAGAN_URL/v1/suppressions/remove" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": "<address>",
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/suppressions/remove`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"address": "<address>",
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"removed": {
"channel": "<channel>",
"address": "<address>",
"reason": "Checked with the owner",
"detail": "<detail>",
"orgWide": true,
"sourceDeliveryId": "<sourceDeliveryId>",
"createdAt": "<createdAt>"
}
}GET /v1/workspace/email-settings#
The workspace's email settings
curl -X GET "$SAPAGAN_URL/v1/workspace/email-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY"const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/email-settings`, {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
},
});
const data = await res.json();Responses
{
"layout": "kontak",
"testRecipients": [
"<testRecipients>"
],
"companyLine": "<companyLine>"
}PUT /v1/workspace/email-settings#
Change the email settings; audited with the reason
layout: the built-in layout emails use when a template names none. testRecipients: the only addresses a test send may go to (at most 20). companyLine: the footer's company line (null clears it).
Request body
| Field | Type | Notes |
|---|---|---|
layout | "kontak" | "branded" | |
testRecipients | string[] | up to 20 items |
companyLine | string or null | max 200 |
reason required | string | min 3, max 2000 |
curl -X PUT "$SAPAGAN_URL/v1/workspace/email-settings" \
-H "Authorization: Bearer $SAPAGAN_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Checked with the owner"
}'const res = await fetch(`${process.env.SAPAGAN_URL}/v1/workspace/email-settings`, {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.SAPAGAN_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"reason": "Checked with the owner"
}),
});
const data = await res.json();Responses
{
"layout": "kontak",
"testRecipients": [
"<testRecipients>"
],
"companyLine": "<companyLine>",
"changed": true
}