Email customization

Tier 1 availability: Shipped today

Tier 1 customization changes approved copy slots in fixed email layouts. Full-template authoring and managed-email extensions have separate boundaries.

Authentication and endpoints

All endpoints require a merchant bearer token and x-organization-slug. Owner/Admin can save and test; Staff needs settings:manage for those actions. Any authenticated organization member can list templates or preview copy. Customer sessions and storefront API keys do not authorize these operations.

Paths below are relative to /api/v1:

curl https://api.preview.litecommerce.io/api/v1/merchant/email-templates \
  -H "Authorization: Bearer <merchant-token>" \
  -H "x-organization-slug: your-store"

The response is { data: [...] }. Each entry includes type, descriptive labels/category, defaults, nullable override fields, resolved sample copy, advertised variables, effective fromName/replyTo, complianceFooter and nullable updatedAt. Use a returned type such as ORDER_CONFIRMATION. The category groups the editor; it does not establish delivery eligibility.

Save copy and restore defaults

Only these fields are writable through Tier 1:

Send only changed fields to PATCH /api/v1/merchant/email-templates/ORDER_CONFIRMATION, with merchant authentication, tenant context and Content-Type: application/json:

{
  "subject": "Your {{store_name}} order is confirmed",
  "heading": "Thanks for your order",
  "bodyText": "We have received your order. Keep this email for your records."
}

Omitted fields keep their saved values. Explicit null clears an override and restores its fallback. To reset this type completely, PATCH all six fields:

{
  "subject": null,
  "heading": null,
  "bodyText": null,
  "ctaLabel": null,
  "fromName": null,
  "replyTo": null
}

Resetting all fields removes the override; the returned updatedAt is then null. Clearing ctaLabel restores the default label rather than hiding a button. Clearing replyTo restores the support-contact fallback. Use explicit null, not an empty reply-to string. An empty PATCH is rejected.

Use only variables advertised for that type, in {{variable_name}} form. Unknown variables and unsupported CTA labels are rejected. Sender fields accept no variables or line breaks. Keep codes, action URLs and credentials out of subjects and saved literal copy; not every variable is suitable for every field. Unexpected request fields are rejected.

Preview an unsaved draft

POST /api/v1/merchant/email-templates/ORDER_CONFIRMATION/preview accepts:

{ "draft": { "heading": "Thank you for shopping with us" } }

Omit draft, or send {}, to preview saved/default copy. The response contains resolved subject, heading, bodyText, ctaLabel, sender/footer values and the available variables. These are server-generated sample values, not a customer/order lookup or rendered HTML document. Preview never saves the draft or sends email.

Sender, links and controlled copy

Without an override, fromName uses the organization name and replyTo uses its resolved support contact. Actual From-address selection and delivery-time Reply-To eligibility remain server controlled. A display-name change does not verify a domain or authorize an arbitrary sender address.

The server supplies applicable action links, CTA destinations, unsubscribe links and the compliance footer. The footer uses the organization's physical support address when configured, otherwise its support contact/name fallback. Maintain these details through Settings & onboarding.

RETURN_APPROVED is a controlled-copy exception: subject, heading and body overrides, including drafts, are accepted but do not replace its effective system copy. It renders no CTA, so a non-empty CTA label is rejected with 400. Sender overrides still apply. Read resolved and preview output to inspect the effective copy rather than assuming every retained override is used.

Send a deliberate sample test

POST /api/v1/merchant/email-templates/ORDER_CONFIRMATION/send-test defaults to SELF: the server resolves the authenticated merchant user's email. Send {} for saved/default copy, or include an unsaved draft:

{ "recipientMode": "SELF", "draft": { "heading": "Sample order heading" } }

Omit recipientEmail for SELF. The sample uses a [Test] subject and sample content; its button is not a live customer action. The success payload is:

{ "sent": true, "skipped": false, "messageId": null }

This reports provider acceptance, not inbox delivery or placement. Deprecated skipped and messageId remain false and null for response compatibility; provider identifiers stay private. Each POST is a new test attempt. After an uncertain result, check before another deliberate send; do not automatically retry and risk another message. A test does not enable the corresponding customer email or establish customer-send quota availability.

Preview deployment, commerce Sandbox and email delivery policy are distinct. For these merchant routes, x-commerce-environment: sandbox selects the provisioned Sandbox's templates and organization settings, including sender name, reply-to and footer details. Omitting the header selects Production data, including on a Preview deployment. Sandbox delivers no external email: send-test returns 503 EMAIL_TEST_DELIVERY_UNAVAILABLE; an unprovisioned Sandbox is refused first with 403. Production-mode test sending still requires permitted recipients and configured delivery. See Environments & schema identity.

Separate extensions and delivery eligibility

Staging also implements separately gated immutable full-template versions, selection and saved-version SELF tests. They are default off; creating or selecting a version does not activate ordinary delivery. Individual email flows retain their own eligibility and activation checks.

Managed-email administration and Newsletter-only ESP synchronization are a separate accepted direction with implementation and activation work remaining. Tier 1 does not provide a campaign composer, general ESP integration, merchant SMTP credentials or a new sending allowance. Template presence, a saved override and a successful test never prove that a Newsletter, stock alert, recovery or other customer lifecycle email is available for that tenant.

See Newsletter & subscribers for subscription state and confirmation behavior, and the API reference for exact schemas.