Notifications And Email

Breyta notification guide for :notify and wait notifications, including email delivery via HTTP channels.

Goal

Send operational notifications and email alerts from flows using canonical notify config.

Quick Answer

Use flow/step :notify for external delivery (:http), and :wait {:notify ...} for approval notifications with action links.

Workspace flow-health digests are a separate product surface:

manage them in app under Settings -> My updates
or from CLI with breyta digests cadence and breyta digests cadence set daily|weekly|monthly
these settings apply only to your user in the current workspace
in-app flow-health updates are on by default for your account
email flow-health updates are opt-in for your account
incident and digest operator pages are currently limited to workspace creators/admins
scheduled digests summarize surfaced incident changes from the previous daily, weekly, or monthly window, with weekly as the default
if there are no surfaced incident changes in that window, no scheduled digest is sent
urgent incident updates are delivered as soon as possible when email delivery includes urgent issues
urgent emails are not held for the next scheduled digest window

Notify Step Pattern

(flow/step :notify :send-email
  {:channels {:http {:connection :sendgrid
                     :path "/v3/mail/send"
                     :method :post
                     :json {:personalizations [{:to [{:email "{{recipient}}"}]}]
                            :from {:email "alerts@example.com"}
                            :subject "{{subject}}"
                            :content [{:type "text/plain" :value "{{message}}"}]}}}
   :data {:recipient "ops@example.com"
          :subject "Flow completed"
          :message "Order {{order-id}} succeeded"}})

Wait Notification Pattern

(flow/step :wait :approval
  {:key "approve:order:123"
   :timeout "2h"
   :notify {:channels {:http {:connection :sendgrid
                              :path "/v3/mail/send"
                              :method :post
                              :json {:personalizations [{:to [{:email "approver@example.com"}]}]
                                     :from {:email "approvals@example.com"}
                                     :subject "Approval required"
                                     :content [{:type "text/plain"
                                                :value "Approve: {{approval-url}}\nReject: {{rejection-url}}"}]}}}}})

Template Support

channels support Handlebars values like {{title}}, {{message}}, {{approval-url}}
wait notifications inject action URL variables automatically
for reusable channel payloads, define a :notification template in :templates

Current Channel Support

flow/step :notify: :http only (SendGrid, Slack, webhooks, custom APIs)
:wait {:notify ...} and checkpoint prompts: optional :http

Common Pitfalls

missing :channels in notify step -> validation error
assuming wait approvals require in-app channels -> use :http notifications with approval/rejection URLs
wrong connection slot in :http channel -> auth/connection errors
expecting native :email channel type -> use :http with an email provider API