Sends, approvals and the action policy
A send is the only way anything leaves Bicycle. A send step delivers a message by email or through one of your workspace's connected actions (Slack, PagerDuty, Jira, a webhook). Every send is recorded in a ledger, and a send can wait for a person's approval in Studio's Approvals inbox.
Where a send goes
| Channel | Config | Notes |
|---|---|---|
to: { channel: "email", recipients: [...] } | 1 to 50 addresses on the step | |
| A connected action | to: { channel: "action", action_id, variables? } | workflow_actions_list shows each action, its required variables and whether it may run on its own; bind variables as literals or ${payload.value.<field>} |
An email list (destination: "dst_...") | deprecated | do not add new ones; put the addresses on the step |
Approval
| Mode | What happens |
|---|---|
manual (recommended) | A person approves in Studio's Approvals inbox, bound to the exact message: subject, body, attached table and picture. Nothing goes out until then. approvers are roles (workflow_owner, workflow_editor, app_owner, app_editor, tenant_admin) or named users; timeout (up to 14 days) and on_timeout (reject) say what happens if nobody answers; review lists artifacts shown alongside. |
auto | No approval: it sends as the step runs. Never on a try run. AI-written text going out under auto is the warning ai_text_unreviewed and a gated change a person acknowledges at publish. |
conditional | Runs as manual. |
An agent or an app can start a workflow; neither can approve its sends. Approving is never a tool.
The action policy (connected tools)
A send through a connected action runs without a person only when a workspace admin has marked that action as allowed to run on its own and the deployment allows it. Otherwise approval: auto on an action step is refused at save with action_requires_approval (the fix switches the step to manual approval), and a send is refused again at send time. The default is that every action send needs a person. Admins manage this under the workflow settings (GET/PUT /api/studio/v1/workflow-action-policy); everyone else reads it.
Never test an action that would page an on-call rotation or open tickets on a real project.
The mail policy
Addresses outside your workspace's own and allowed domains are, depending on the admin's setting, refused (recipient_domain_not_allowed), required to go through a manual approval (external_recipient_needs_approval, the default), or allowed with a warning. Only a workspace admin changes the policy (/api/studio/v1/workflow-mail-policy).
On a preview environment, mail goes only to addresses on the deployment's allowlist; any other address is an error at save (recipient_not_allowed) and is withheld at send time.
Once and only once
The idempotency_key (allowed pieces: ${run.logical_date}, ${partition.<dim>}, ${row.<col>}) names one send. A key that was already sent is never sent again: a re-run for the same date joins the earlier send instead of duplicating it. That is the ledger.
per: "row" (one send per payload row) validates, but this build refuses it at plan time (per_row_not_supported). Send one message that lists the rows instead.
Caps
- At most 50 recipients on a step.
max_sends_per_rundefaults to 1 and goes up to 500; over it the step fails withsend_cap_run.- A workspace sends to at most 500 recipients per day (UTC); over it,
send_cap_daily. - An approval waits at most 14 days.
What the receipt says
The send step's output is a receipt: { node, destination, state, approval_id?, idempotency_key }. Its state follows the send: awaiting_approval, then sent, or rejected, expired, failed. A message is delivered only when the state is sent; an app that started the workflow must not tell the viewer "sent" before then.
What a person sees in Approvals
The subject, the rendered body, the attached table and picture, who is asked to approve, the deadline, and Approve and send or Reject. A rejected send is recorded and not retried; a later run with a new key can send again.
Gated at publish
Adding or changing a send step (its recipients, its approval), and anything upstream of a send that needs no approval, is a gated change: a person publishes the revision in Studio. See Workflows overview.
Outcome notifications
Separate from the sends inside the workflow, a workflow tells one person when a run succeeds or fails; see Schedules and failure routing.