One API for every application message.

curl -X POST "$COMMS_URL/api/provision/apps" \
  -H "X-Provisioning-Key: $COMMS_PROVISIONING_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FlowBase",
    "slug": "flowbase",
    "ratePerMinute": 120,
    "scopes": ["SEND", "READ", "PROVIDERS", "TEMPLATES"]
  }'

{
  "app": {
    "slug": "flowbase",
    "sandboxMode": true
  },
  "apiKey": "cs_test_...",
  "alreadyRegistered": false
}

import { CommsProvisioningClient } from "@/lib/comms-client";

const provisioning = new CommsProvisioningClient({
  baseUrl: process.env.COMMS_URL!,
  provisioningKey: process.env.COMMS_PROVISIONING_KEY!,
});

const result = await provisioning.provisionApp({
  name: "FlowBase",
  slug: "flowbase",
  scopes: ["SEND", "READ", "PROVIDERS", "TEMPLATES"],
});

// Persist result.apiKey into your server secret store when it is not null.

import { CommsClient } from "@/lib/comms-client";

export const comms = new CommsClient({
  baseUrl: process.env.COMMS_URL!,
  appId: process.env.COMMS_APP_ID!,
  apiKey: process.env.COMMS_API_KEY!,
});

const result = await comms.sendEmail({
  to: user.email,
  subject: "Request approved",
  body: "<p>Your request REQ-0042 was approved.</p>",
  idempotencyKey: request.id + "-approved-email",
  metadata: { requestId: request.id },
});

// result: { id: "cmr...", status: "QUEUED" }

POST /api/v1/templates

{
  "key": "request-approved",
  "channel": "SMS",
  "name": "Request approved",
  "body": "Hi {{firstName}}, request {{reference}} was approved."
}

POST /api/v1/messages

{
  "channel": "SMS",
  "to": "233241234567",
  "templateKey": "request-approved",
  "variables": {
    "firstName": "Ama",
    "reference": "REQ-0042"
  }
}

POST /api/v1/provider-configs

{
  "providerType": "SMTP",
  "name": "Company SMTP",
  "priority": 1,
  "config": {
    "host": "mail.example.com",
    "port": 587,
    "username": "[email protected]",
    "password": "...",
    "from": "MyApp <[email protected]>"
  }
}

PATCH /api/v1/app

{
  "sandboxMode": false
}

{
  "event": "message.status",
  "message": {
    "id": "cmr...",
    "channel": "SMS",
    "status": "DELIVERED",
    "toAddress": "233...",
    "providerName": "arkesel",
    "providerMessageId": "...",
    "errorMessage": null,
    "attempts": 1,
    "sentAt": "2026-07-03T10:00:00.000Z",
    "metadata": { "requestId": "REQ-0042" }
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

const rawBody = await request.text();
const received = request.headers.get("x-comms-signature") ?? "";
const timestamp = request.headers.get("x-comms-timestamp") ?? "";
const expected = createHmac("sha256", process.env.COMMS_WEBHOOK_SECRET!)
  .update(timestamp + "." + rawBody)
  .digest("hex");

const valid = received.length === expected.length && timingSafeEqual(
  Buffer.from(received),
  Buffer.from(expected),
);