SapaganDocs sapagan.com

API reference

Email

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

Accepted keys Server key

Parameters

NameInTypeNotes
kindquery"row" | "email"
curl -X GET "$SAPAGAN_URL/v1/email-templates" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
kind required"row" | "email"
name requiredstringmin 1, max 120
descriptionstringmax 500
content requiredobject
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": {}
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden, 409 Conflict. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key

Parameters

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

Responses

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

Example response 200

{
  "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)

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 120
descriptionstringmax 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>"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden, 404 Not found, 409 Conflict. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Parameters

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

Responses

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

Example response 200

{
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
hoursqueryinteger
curl -X GET "$SAPAGAN_URL/v1/email/deliverability" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

{
  "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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/email/designer" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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

Accepted keys Server key Store key Store token

curl -X GET "$SAPAGAN_URL/v1/layouts" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK. Errors use the error body.

Example response 200

{
  "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.

Accepted keys Server key

Request body

FieldTypeNotes
name requiredstringmin 1, max 200
mjml requiredstringmin 1, max 100000
lockedbooleandefault false
reason requiredstringmin 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"
  }'

Responses

201 Created, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 201

{
  "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

Accepted keys Server key Store key Store token

Parameters

NameInTypeNotes
idpathstring required
curl -X GET "$SAPAGAN_URL/v1/layouts/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>",
  "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.

Accepted keys Server key

Parameters

NameInTypeNotes
idpathstring required

Request body

FieldTypeNotes
namestringmin 1, max 200
mjmlstringmin 1, max 100000
lockedboolean
reasonstringmax 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"
  }'

Responses

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

Example response 200

{
  "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.

Accepted keys Store key Store token

curl -X GET "$SAPAGAN_URL/v1/scope/email/starters" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

{
  "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).

Accepted keys Server key

Parameters

NameInTypeNotes
channelquery"email" | "push" | "inbox" | "webhook" | "whatsapp"
addressquerystring
reasonquery"hard_bounce" | "complaint" | "account_suppressed" | "unsubscribe_all" | "manual" | "invalid_token"
limitqueryinteger
cursorquerystring
curl -X GET "$SAPAGAN_URL/v1/suppressions" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

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

Example response 200

{
  "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).

Accepted keys Server key

Request body

FieldTypeNotes
channel"email" | "push" | "inbox" | "webhook" | "whatsapp"default "email"
address requiredstringmin 1, max 512
reason requiredstringmax 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"
  }'

Responses

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

Example response 200

{
  "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

Accepted keys Server key

curl -X GET "$SAPAGAN_URL/v1/workspace/email-settings" \
  -H "Authorization: Bearer $SAPAGAN_KEY"

Responses

200 OK, 403 Forbidden. Errors use the error body.

Example response 200

{
  "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).

Accepted keys Server key

Request body

FieldTypeNotes
layout"kontak" | "branded"
testRecipientsstring[]up to 20 items
companyLinestring or nullmax 200
reason requiredstringmin 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"
  }'

Responses

200 OK, 400 Invalid request, 403 Forbidden. Errors use the error body.

Example response 200

{
  "layout": "kontak",
  "testRecipients": [
    "<testRecipients>"
  ],
  "companyLine": "<companyLine>",
  "changed": true
}