Email Module — Admin

Operator-configurable email: the outbound provider (Resend or SMTP), store brand tokens rendered into transactional/auth emails, per-template content overrides, and the block-based campaign builder.

Source: api-modules/email/src/controllers/*, settings registry api-modules/settings/src/registry/{admin/email.ts,store/email.ts,store/branding.ts}.

Configuration (settings)

All configuration is stored in the settings registry and edited via the standard settings UI (PUT /admin/settings, PUT /store/settings). The live mailer reads provider + brand at send time — changes apply on the next send, no redeploy.

Provider — admin.email

When the provider is unconfigured (blank host / key), the mailer falls back to the SMTP_* env vars, so local dev and fresh installs keep working. Both providers are backed by @opencoredev/email-sdk (its resend and smtp adapters).

Brand tokens — store.branding + store.email

Transactional and auth emails inherit these. Campaign emails do NOT — they are fully standalone.

The storefront URL used in emails is read from store.storefront_urls.store_url, falling back to store.seo.canonical_base_url when blank.

Auth email link paths — store.email

Auth emails link to the storefront (not the API). Each link is built as store.storefront_urls.store_url (falling back to store.seo.canonical_base_url) + the configured path + the better-auth token. Defaults match the store UI's routes; override per deployment.

If no store base URL is set, the email keeps better-auth's own server URL.

Endpoints

Provider test

POST /admin/email/test — send a test email to verify the active provider config. Permission: emailTemplate:test.

// body
{ "to": "me@example.com" }

Transactional template overrides

Every template — notification templates like order.placed, the guest-checkout order confirmation guest_order.confirmation (the email a guest gets with their tokenized tracking link), the vendor-application lifecycle emails (vendor.application.submitted, vendor.application.approved, vendor.application.rejected, role vendor_member), the back-in-stock emails (back_in_stock.available to the customer — the only channel that can reach a guest subscriber — and back_in_stock.vendor_alert to vendor_member, the operator-triggered restock nudge), and the auth/default emails (auth.reset_password, auth.magic_link, auth.verification, auth.change_email, auth.delete_account, auth.password_changed, auth.welcome) — is data-driven: it has an editable default subject / heading / body (HTML with {{variables}}). The editor shows the real defaults (prefilled, not blank); you edit the body directly. At send, variables are interpolated and the body is rendered inside the brand shell (logo header + footer). The legacy React templates remain only as a fallback for any template without a registered default. Auth emails always send (the enabled toggle is ignored for them — you can't disable e.g. a password reset).

Permission: emailTemplate:view (read), emailTemplate:update (write), emailTemplate:test.

Body/subject/heading support {{variable}} placeholders. Common variables (customer_name, store_name, store_url, support_email, accent_color) are always available; every top-level scalar field of the event payload is exposed in snake_case (money fields formatted, e.g. {{grand_total}} → ₹1250.00, with the raw value under {{grand_total_raw}}). Auth emails expose {{url}} (and {{new_email}} for email-change).

// PUT body
{
  "enabled": true,
  "subject": "Order {{order_number}} confirmed",
  "heading": "Thanks, {{customer_name}}!",
  "body": "<p>Hi {{customer_name}}, your order is on its way.</p><p>Total: {{grand_total}}.</p>"
}

Campaigns (block builder)

Campaigns ride the existing broadcast engine (audience resolution, worker fan-out, scheduling, status counters — see notifications.md). The body is built from safe blocks and rendered standalone (no transactional brand chrome).

Permissions: campaignTemplate:view (read), campaignTemplate:manage (write), notifications:broadcast (send).

Blocks: heading, text, image, logo, button, social, divider, spacer. Text/heading/button fields support {{variables}}. There is no raw-HTML block.

// POST /admin/campaigns/send
{
  "audience": { "type": "all_customers" },          // or { "type": "user_ids", "userIds": [...] }
  "subject": "Summer sale is live",
  "previewText": "Up to 40% off",
  "templateId": "…",        // OR provide "blocks": [...] inline
  "scheduleFor": "2026-07-01T09:00:00Z"   // optional; send-now if omitted
}

A templateId snapshots the template's subject + blocks at send time, so later edits never mutate an in-flight campaign.