Skip to content

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.

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

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

Start with recipes-delivery-notifications for a step-by-step walkthrough with runnable code and integration tests.

  • Requires: delivery
  • Activation: always on (not toggleable)
  • Registers extension: emailAppTransport → app, deliveryChannel → email