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
idintegeroptionalnamestringoptionaltypestringoptionalemail, sms or webhook.configobjectoptionaldescriptionstring or nulloptionalenabledbooleanoptionalcreated_atstringoptionalupdated_atstringoptionalChannel settings
type | config |
|---|---|
email | smtp_host and from_email (required), smtp_port (default 587), smtp_user, smtp_password, use_tls, use_ssl. |
sms | Either Twilio settings account_sid, auth_token and from_number, or a gateway url (with optional api_key). |
webhook | url (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
/notification-channelsLists channels. GET /notification-channels/{channel_id} returns one.
Query parameters
typestringoptionalenabledbooleanoptionalResponses
Add a channel
/notification-channelsAdds a channel. Requires the admin role.
Body
namestringrequiredtypestringrequiredemail, sms or webhook.configobjectrequireddescriptionstringoptionalenabledbooleanoptionaltrue.Responses
Change a channel
/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_idintegerrequiredBody
Any of name, type, config, description and enabled.
Responses
Delete a channel
/notification-channels/{channel_id}Deletes a channel that no workflow uses. Requires the admin role.
Path parameters
channel_idintegerrequiredResponses
{"status": "deleted"}.detail lists the workflows.Send a test message
/notification-channels/{channel_id}/test-sendSends a real test message through the channel, so you can check its settings. Requires the admin role.
Path parameters
channel_idintegerrequiredBody
tostringoptionalfrom_email), or a phone number for SMS channels. Not used for webhooks.Response fields
statusstringoptionalsent.channel_typestringoptionaltostringoptionalResponses
detail gives the HTTP status when there is one.