channel-email
Wires an EmailTransport (typically mail-transport-smtp in production, createInMemoryTransport() in tests) into the delivery system as the email channel. Requires delivery; pass an EmailChannelOptions with a transport and a resolveEmail function that maps a user ID to their email address. Mails render from stored templates (renderer-mail-html): a notification routed to this channel needs template + meta on r.notification, otherwise its delivery fails. Pass tenantTransport: tenantMailTransport (from mail-foundation) to send the notifications declared with tenantTransport: true through the sending tenant’s own configured provider: a broken provider fails the send, a tenant without one uses the app transport; every other notification (password reset, sign-in) always goes through the app transport. transport may be left out when tenantTransport is set, but then only notifications declared with tenantTransport: true are delivered: every other notification (password reset, sign-in, invitations) fails with missing_credentials, so an app without an app SMTP server must mark every notification that should go out or keep an app transport. Notifications declared with unsubscribe: true get a signed data.unsubscribeUrl from delivery, which turns into the List-Unsubscribe headers.
Quick example
Section titled “Quick example”From recipes-delivery-notifications — the smallest working mount:
// Delivery Notifications Sample//// A support ticket is created and its assignee is notified via inApp, email// and push. The mail is a stored template: `r.notification` declares the// variables, the default text and the subject, the boot seed writes the text// into the template store, and a tenant can override it there.//// The feature code only declares WHAT to notify. HOW is handled by Delivery.
import { buildEntityTable, createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";import { createEntity, createTextField, defineFeature, QnTypes, qn, templateVariable,} from "@cosmicdrift/kumiko-framework/engine";import { z } from "zod";
// --- Entity ---
export const ticketEntity = createEntity({ name: "ticket", table: "read_sample_delivery_tickets", fields: { title: createTextField({ personal: false, reason: "is_business_data", required: true, maxLength: 200, }), description: createTextField({ personal: false, reason: "is_business_data", maxLength: 2000 }), assigneeId: createTextField({ personal: "ref" }), priority: createTextField({ personal: false, reason: "is_business_data", required: true }), // "low" | "normal" | "critical" status: createTextField({ personal: false, reason: "is_business_data", required: true }), },});
export const ticketTable = buildEntityTable(ticketEntity);
function ticketExecutor() { return createEventStoreExecutor(ticketTable, ticketEntity, { entityName: "ticket" });}
// --- Feature ---
export const TICKET_ASSIGNED = qn("support", QnTypes.notify, "ticket-assigned");
export const supportFeature = defineFeature("support", (r) => { r.requires({ features: ["delivery"] });
r.entity(ticketEntity);
r.notification({ name: "ticket-assigned", variables: { ticketId: templateVariable.text({ required: true }), title: templateVariable.text({ required: true }), description: templateVariable.text({ required: true }), priority: templateVariable.text({ required: true }), url: templateVariable.link({ required: true }), }, template: { en: { body: '<h1>New ticket: <span data-variable="title"></span></h1><p><span data-variable="description"></span></p><p>Priority: <span data-variable="priority"></span></p><p><a data-button href="{{url}}">Open ticket</a></p>', }, }, meta: { en: { subject: "Support ticket #{{ticketId}} ({{priority}})" } }, // inApp and push build their own short text; email renders the stored // template with the notify data as variables. templates: { inApp: (data) => ({ title: `New ticket: ${data["title"]}`, body: (data["description"] as string) || "A ticket was assigned to you.", }), push: (data) => ({ title: "New ticket", body: `${data["title"]} (${data["priority"]})`, }), }, });
r.writeHandler({ name: "ticket:create", schema: z.object({ title: z.string().min(1), description: z.string().optional(), assigneeId: z.uuid().optional(), priority: z.enum(["low", "normal", "critical"]), status: z.string().default("open"), }), handler: async (event, ctx) => { const created = await ticketExecutor().create(event.payload, event.user, ctx.db); const assigneeId = event.payload.assigneeId; // No assignee, no notification. if (!created.isSuccess || assigneeId === undefined) return created; if (ctx.notify === undefined) { throw new Error("ticket:create needs ctx.notify, mount the delivery feature"); } const ticketId = created.data.id; await ctx.notify(TICKET_ASSIGNED, { to: assigneeId, // Known key per ticket: dedups a replayed handler and lets an admin screen ask // channel-in-app:query:read-state-by-keys whether the assignee has seen it. idempotencyKey: `ticket-assigned:${ticketId}`, data: { ticketId, title: event.payload.title, description: event.payload.description ?? "", priority: event.payload.priority, url: `https://app.example.com/support/tickets/${ticketId}`, }, }); return created; }, access: { roles: ["Admin", "Support"] }, });});📄 On GitHub: samples/recipes/delivery-notifications/src/feature.ts
How it fits
Section titled “How it fits”What this feature needs to run (Requires).
flowchart TB
n_channel_email["channel-email"]
subgraph how_reqs["Requires"]
n_delivery["delivery"]
end
n_delivery --> n_channel_email
Getting started
Section titled “Getting started”Start with recipes-delivery-notifications for a step-by-step walkthrough with runnable code and integration tests.
Dependencies
Section titled “Dependencies”- Requires:
delivery - Activation: always on (not toggleable)
Extensions & cross-feature APIs
Section titled “Extensions & cross-feature APIs”- Registers extension:
emailAppTransport→app,deliveryChannel→email