Skip to main content

Notification channels

A notification channel holds the connection settings for one way of sending messages: an SMTP server for email, an SMS provider, or a webhook. Workflow steps such as Send Email and Send SMS refer to a channel by its ID and add the recipients and text. See Notifications.

Listing works for operators and admins. Adding, changing, deleting and test-sending need the admin role.

The channel object​

idintegeroptional
The channel ID.
namestringoptional
The name. Unique.
typestringoptional
email, sms or webhook.
configobjectoptional
The connection settings. See Channel settings.
descriptionstring or nulloptional
A description.
enabledbooleanoptional
Whether workflows can send through it.
created_atstringoptional
When the channel was added.
updated_atstringoptional
When it was last changed.

Channel settings​

typeconfig
emailsmtp_host and from_email (required), smtp_port (default 587), smtp_user, smtp_password, use_tls, use_ssl.
smsEither Twilio settings account_sid, auth_token and from_number, or a gateway url (with optional api_key).
webhookurl (required, http:// or https://) and optional headers.

Secrets​

Passwords, tokens and API keys are never returned. They come back as ********. Operators also see header values masked and URLs reduced to scheme and host. When you change a channel, send ******** (or leave the field out) to keep a stored secret.

Channel URLs and SMTP hosts may not point at the site node itself (loopback), link-local or cloud metadata addresses. Private network addresses are allowed. Your administrator can allow specific internal targets.

List channels​

GET/notification-channels

Lists channels. GET /notification-channels/{channel_id} returns one.

Query parameters​

typestringoptional
Only channels of this type.
enabledbooleanoptional
Only enabled or only disabled channels.

Responses​

200
An array of channels.
401
You are not signed in.
404
No channel with this ID (single channel only).

Add a channel​

POST/notification-channels

Adds a channel. Requires the admin role.

Body​

namestringrequired
The name. Must be unique.
typestringrequired
email, sms or webhook.
configobjectrequired
descriptionstringoptional
A description.
enabledbooleanoptional
Defaults to true.

Responses​

201
The channel was added. Returns the channel.
403
You are not an admin.
409
A channel with this name already exists.
422
The type is not valid, or a required setting is missing or malformed.

Change a channel​

PATCH/notification-channels/{channel_id}

Changes one or more fields. Send only the fields you want to change. Masked secrets sent back unchanged keep their stored values. Requires the admin role.

Path parameters​

channel_idintegerrequired
The channel.

Body​

Any of name, type, config, description and enabled.

Responses​

200
The channel was changed. Returns the channel.
403
You are not an admin.
404
No channel with this ID.
409
Another channel has this name.
422
A setting is not valid.

Delete a channel​

DELETE/notification-channels/{channel_id}

Deletes a channel that no workflow uses. Requires the admin role.

Path parameters​

channel_idintegerrequired
The channel.

Responses​

200
{"status": "deleted"}.
403
You are not an admin.
404
No channel with this ID.
409
A workflow still uses the channel. detail lists the workflows.

Send a test message​

POST/notification-channels/{channel_id}/test-send

Sends a real test message through the channel, so you can check its settings. Requires the admin role.

Path parameters​

channel_idintegerrequired
The channel.

Body​

tostringoptional
The recipient: an email address for email channels (defaults to the channel's from_email), or a phone number for SMS channels. Not used for webhooks.

Response fields​

statusstringoptional
sent.
channel_typestringoptional
The channel type.
tostringoptional
The recipient, for email and SMS.

Responses​

200
The message was sent.
403
You are not an admin.
404
No channel with this ID.
422
The channel is disabled, a recipient is missing, or the target address is not allowed.
502
The destination refused or couldn't be reached. detail gives the HTTP status when there is one.
Was this page helpful?