Notification templates — list, read, propose, edit

/templates

The notification templates your account can use: your own proposals and MauKirim’s reviewed system defaults. A template must be approved before POST /messages/send will send it, and a send’s variables must name exactly the template’s variables (and, for a list section, its lists fields).

Method	Path	Scope
GET	/templates	notification or read
GET	/templates/{id}	notification or read
POST	/templates	notification
PUT	/templates/{id}	notification
POST	/integrations/shopify/templates	notification

A notification key may list templates so an integration can learn each template’s placeholders without a second key.

The template object

{
  "id": "shopify_order_shipped_id",
  "name": "Shopify: pesanan dikirim",
  "body": "Halo {{customer_first_name}}, pesanan #{{order_number}} dari {{shop_name}} sudah dikirim melalui {{tracking_company}}. Nomor resi: {{tracking_number}}.",
  "variables": ["customer_first_name", "order_number", "shop_name", "tracking_company", "tracking_number"],
  "lists": [],
  "status": "approved",
  "attachment": null,
  "attachmentMode": "none",
  "system": true,
  "approval": "review",
  "integration": null,
  "integrationKey": null,
  "revision": null
}

Field	Meaning
variables	Top-level names a send must supply, in the order they appear
lists	{ name, fields } for each {{#name}}…{{/name}} section; the send passes an array of 0–10 objects with exactly those fields
status	pending, approved or rejected
system	true for a MauKirim default every account can send; it cannot be edited
attachmentMode	none, static (reviewed bytes are always attached) or per_send (each send names an upload)
approval	How an approved template was approved: review (an administrator), provisioned (copied from a reviewed system template) or rules (an integration edit that passed the automatic rules); null otherwise
integration	shopify on your account’s own copy of a Shopify template, otherwise null
integrationKey	For such a copy, the system template it was made from, e.g. shopify_order_created_id
revision	{ id, name, body, variables, status, updatedAt } for an edit waiting for review (or rejected) while the template keeps sending its approved text; null otherwise

System templates

Every account can send order_update (order_id) and eight Shopify order templates, in Indonesian (_id) and English (_en):

id	variables
shopify_order_created_id / _en	customer_first_name, shop_name, order_number, total_price
shopify_order_paid_id / _en	customer_first_name, order_number, total_price, shop_name
shopify_order_shipped_id / _en	customer_first_name, order_number, shop_name, tracking_company, tracking_number
shopify_order_cancelled_id / _en	customer_first_name, order_number, shop_name

GET /templates

curl https://app.maukirim.com/api/v1/templates -H "Authorization: Bearer mk_live_…"

200 → { "ok": true, "templates": [Template, …] }, newest first, at most 100.

GET /templates/{id}

200 → { "ok": true, "template": Template }. Another account’s template, or an unknown id, is 404 not_found.

POST /templates

Proposes a template. It starts pending and cannot be sent until an administrator approves it.

curl -X POST https://app.maukirim.com/api/v1/templates \
  -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"name":"Shipped","body":"Order {{order_number}} shipped via {{tracking_company}}."}'

Field	Type	Notes
name	string	1–64 characters
body	string	1–1024 characters. Placeholders are {{lower_snake}}; at most 8 top-level names; list sections do not nest
attachmentMode	string?	none (default), static or per_send
attachmentUploadId	string?	An upload from POST /messages/media, required for static

201 → { "ok": true, "template": Template }.

PUT /templates/{id}

Replaces the whole definition of a template your account owns and sends it back to review: an approved template edited here becomes pending and cannot be sent until it is approved again. The body is the same as POST. A system template or another account’s template is 404 not_found.

200 → { "ok": true, "template": Template, "revision": null, "violations": [] }.

Integration templates (integration is set) are text-only and are not sent back to review. An edit that passes the automatic rules is approved at once (200, approval: "rules"). Otherwise the answer is 202 with the template unchanged — it keeps sending its approved text — plus the pending revision and the violations that sent it to review; editing again replaces that revision. The rules:

Violation	When
variable_not_allowed	A placeholder the integration cannot fill. For Shopify: order_number, customer_first_name, customer_name, total_price, item_count, first_item, payment_status, shop_name, tracking_number, tracking_company, tracking_url
list_block	A {{#list}} section
link	A URL or domain in the text
phone_number	Eight or more digits in a row in the text
too_long	More than 500 characters
rate_limited	More than 20 automatic approvals for the account in 24 hours

POST /integrations/shopify/templates

Gives your account its own approved copy of each Shopify order template in one language, so they can be edited. Idempotent: later calls return the same copies.

curl -X POST https://app.maukirim.com/api/v1/integrations/shopify/templates \
  -H "Authorization: Bearer mk_live_…" -H "Content-Type: application/json" \
  -d '{"language":"id"}'

language is id or en. 200 → { "ok": true, "templates": [Template, …] }, each with integration: "shopify" and integrationKey naming its system template.

Errors

400 invalid_input (missing name or body, malformed placeholders), 401, 403 api_key_scope_denied, 404 not_found, 410 media_unavailable (the attachment upload expired), 500.