Notify (ctx.notify)

ctx.notify.send sends a notification to a notification group or a single notification recipient configured in CoCoCo. The message goes out by email, to the recipients whose delivery channel is email.

ctx.notify.send({
  group = "…",        -- group ID or group name
  recipient = "…",    -- or: recipient ID
  subject = "…",      -- required
  body = "…",         -- required, plain text
  bodyHtml = "…",     -- optional HTML version
}) -> (ok, { status, recipientCount }?)

Give one of group or recipient (if you give both, group is used). A group can be named by ID or by name; a recipient only by ID. body is always required and serves as the plain-text version when you also send bodyHtml.

local ok, receipt = ctx.notify.send({
  group = "ops-pagers",
  subject = "Queue depth high",
  body = "The prepress queue has 120 waiting jobs.",
})
if not ok then error(receipt) end

if receipt == nil then
  return { sent = true }
end
return { sent = true, status = receipt.status, recipientCount = receipt.recipientCount }

Results and errors

• On success the receipt is { status, recipientCount }, where recipientCount is the number of email addresses the message was sent to. The declared type also allows nil, so the example checks it before reading fields.
• A group or recipient with no email recipient returns false, "notify.send: No email recipients resolved".
• A missing or empty subject, body or target, or a group or recipient that does not exist or that the script's identity cannot access, raises an error. So does a failure of the email service itself.

Rendering the message from a template

Keep message wording in stored templates and render it before sending:

local VARIABLES = { customer = "Acme Corp", orderNumber = "SO-10428" }

local ok, text = ctx.template.render("order-confirmation.txt", VARIABLES)
if not ok then error(text) end

local htmlOk, html = ctx.template.render("order-confirmation.html", VARIABLES)
if not htmlOk then error(html) end

local sent, receipt = ctx.notify.send({
  group = "order-desk",
  subject = "Order " .. VARIABLES.orderNumber .. " is confirmed",
  body = text,
  bodyHtml = html,
})
if not sent then error(receipt) end
return { sent = sent }

The older two-argument form ctx.notify.send(targetId, { subject, body }) still works but is deprecated. Use the single-table form.