Overview

Channel is how your backend reaches a person — the order-confirmation email, the SMS sign-in code, a WhatsApp notice, or a device push. You declare a template on a medium, fill a {{field}} body catalog, and send from a Flow with fx.send.

For developers wiring Mailpit locally and Resend / Taqnyat / FCM in production — templates and drivers first, never vendor SDKs inside do.

Smallest Example

import { channel } from "okengine";
import { z } from "zod";

const mail = channel.email({ from: "Notes <notes@localhost>" });

export const noteCreatedMail = mail.template("note-created", {
  locales: ["en"],
  schema: z.object({
    id: z.string(),
    title: z.string(),
  }),
});

import { on, flow } from "okengine";
import { noteCreatedMail } from "@/core/channel";
import { noteCreated } from "./signals";

export const onCreated = on(
  noteCreated,
  flow("notes.onCreated", {
    do: async (payload, fx) => {
      await fx.send(noteCreatedMail, {
        to: "you@localhost",
        data: { id: payload.id, title: payload.title },
      });
    },
  }),
);

Progressive Patterns

From a bare send to catalog bodies, locale, and same-medium failover:

await fx.send(noteCreatedMail, {
  to: "alice@example.com",
  data: { id: "n1", title: "Hello" },
});

Declaration Reference

Medium options

Template options

Empty name throws TypeError: channel.template: name is required.

There is no subject / body / html on declare — those belong in the catalog.

fx surface

fx.send options

Dry-run records would have fired and never contacts a provider. Undeclared send → OKE1004 UNDECLARED_SEND.

Per-environment drivers

Email defaults from DRIVER_DEFAULTS.channel.email. SMS / WhatsApp / push are opt-in:

import { defineConfig } from "okengine/config";

export default defineConfig({
  drivers: {
    channel: {
      email: { dev: "smtp", test: "console", prod: "smtp" },
      // sms: { prod: "taqnyat" },
      // whatsapp: { prod: "wa-cloud" },
    },
  },
  images: {
    channel: { email: "axllent/mailpit:v1.31.1" },
  },
});

Env knobs: Environment variables. Local SMTP catcher: Mailpit.

The Capabilities of Channel

Troubleshooting

Learn more

• Email — drivers, catalog, Mailpit
• SMS — fx.sendOtp / fx.verifyOtp
• WhatsApp — channel.whatsapp + boot drivers
• Push — FCM / Web Push binding
• Receipts — ledger, outcomes, suppression
• OTP plugin — /auth/otp/* over Channel
• fx — fx.send options
• i18n — Channel catalogs vs fx.t

Next