Communications

Unified module, channel-scoped Admin paths

One communications module owns all three channels. Admin routes register at the router root — there is no /communications prefix:

Config nests push settings under pushNotifications (legacy key name); Admin API paths use /push.

API surfaces

Legacy grpc-sdk clients (grpcSdk.email, grpcSdk.pushNotifications, grpcSdk.sms) route to communications automatically.

Templates: EmailTemplate vs CommunicationTemplate

EmailTemplate — email-only Handlebars templates. Full Admin CRUD at /email/templates. Variables are auto-extracted from {{placeholders}} in subject and body on create. Reference by templateName when calling POST /email/send or grpcSdk.email.sendEmail.

CommunicationTemplate — unified multi-channel template stored in the database. One document covers every channel the message uses:

CommunicationTemplate documents are exportable/importable via state export (communicationTemplates resource type). Provision at deploy time alongside EmailTemplates.

For EmailTemplate, use Admin REST (POST /email/templates) or MCP post_email_templates. For CommunicationTemplate, prefer GitOps state import or direct database provisioning today. gRPC RegisterCommunicationTemplate is the orchestrator registration hook (server-side grpc-sdk only); it currently returns a minimal placeholder response — full unified Admin REST CRUD for CommunicationTemplate is not exposed yet.

Sending with templateName

// Email — template by name (server-side only)
await grpcSdk.email!.sendEmail("WelcomeEmail", {
  email: "user@example.com",
  variables: { name: "Alex" },
});

// Orchestrator — multi-channel broadcast
await grpcSdk.communications!.sendToMultipleChannels(
  ["email", "push"],
  "BEST_EFFORT",
  {
    recipient: "user@example.com",
    subject: "Order shipped",
    body: "Your order {{orderId}} is on the way",
    variables: { orderId: "ORD-42" },
  }
);

Orchestration

The orchestrator coordinates delivery across channels through two Admin API entry points:

POST /send/multiple returns { successCount, failureCount, results[] }. POST /send/fallback returns { successfulChannel, messageId, attempts[] }.

Orchestration config (retryAttempts, retryDelay, timeout, fallbackTimeout) lives under communications.orchestration.

Migration from v0.16

Standalone email, sms, and push-notifications modules are deprecated. Communications is a drop-in replacement:

1. Deploy — register Communications instead of three separate modules.
2. Config — nest legacy keys under communications (example below).
3. Code — existing grpcSdk.email, grpcSdk.pushNotifications, grpcSdk.sms calls continue unchanged.
4. MCP — use ?modules=communications or aliases ?modules=email,push,sms. push-notifications is not a valid alias.

communications:
  active: true
  email:
    active: true
    transport: sendgrid
    sendingDomain: example.com
    transportSettings:
      sendgrid:
        apiKey: "…"
  pushNotifications:   # config key — Admin paths use /push
    active: true
    providerName: firebase
    firebase:
      projectId: "…"
  sms:
    active: true
    providerName: twilio
    twilio:
      accountSID: "…"
      authToken: "…"
  orchestration:
    retryAttempts: 3
    fallbackTimeout: 5000

On first boot, communications can auto-merge legacy top-level email, pushNotifications, and sms config into the unified namespace when channel values still match defaults. Legacy gRPC service names are preserved on the unified Communications gRPC service.

See Migration guide.