Automations

Every write to your store is recorded as an event. A flow turns those events into work: an email from one of your own templates, a note or a tag on an order, a cancellation, a signed webhook, a call that wakes your agent, a pause. Flows run on the same log, the same topic-and-filter vocabulary and the same retry schedule as events, so you and your agent can automate a store without running a receiver of your own.

1. The model

A flow run is one delivery — the same kind of delivery a subscription gets (events). Formahand evaluates every enabled flow against every recorded event exactly as it evaluates a subscription (the topic patterns first, then the filter), applies your store's kill switch and the loop protection of §6, and queues at most one run per (flow, event) pair. Retries and their backoff (immediately, then 1 min, 5 min, 30 min, 2 h, 8 h), the pending → delivered | failed states, POST /api/deliveries/:id/retry, retention and the run log are the subscription machinery unchanged.

A run never holds up the write that caused it. Runs are queued while the write is being answered and started straight afterwards: a write that left runs due answers with X-Formahand-Deliveries-Due: <n> and Formahand picks them up at once rather than waiting. Anything still outstanding — a retry, a wait that has come due, a write made on the storefront itself such as a newsletter sign-up — is picked up again every ten minutes.

Email a flow produced is sent for you. A send_email step hands Formahand the rendered message and Formahand sends it as your store, then writes the outcome back into the run: the step is queued until the answer comes back, then done with its message ids, or failed with mail_failed. That is also why a flow that sends email needs a sending address it may use before it can be switched on (§18).

2. Email templates

Every email your store sends comes from a template you own. A template has a key (^[a-z0-9]+(-[a-z0-9]+)*$, 1–60 characters), a name, a subject, an HTML body and a text body. Subject and bodies are templates (§3); an empty text body is derived from the rendered HTML for you. variables is documentation — the declared inputs the dashboard's variables help shows, defaulted to the paths the template actually references when you create one without them. Every write validates the three template fields and answers 400 { error, field: "subject" | "bodyHtml" | "bodyText", position } on a syntax error.

System templates are seeded in every store, ready to edit (isSystem: true, and their key is fixed):

The order-confirmation and order-shipped defaults reproduce the copy Formahand sent before templates existed — same wrapper, table, totals rows, address block and tracking button — so nothing a buyer sees changed until a merchant edited one. Formahand's own buyer emails render through your template: the order confirmation and the shipping email read your store's template for that key and fall back to the built-in default if it is missing or no longer renders.

Seeding is idempotent per key. A template you have edited keeps your edits when Formahand ships a new or improved default, and a custom template you deleted stays deleted. A brand-new store gets its system templates on first use.

Editing and reset. PUT on a system template keeps it a system template; a template counts as modified when its subject, bodies, fromName or replyTo differ from the default. POST …/reset restores the default subject, bodies and variables and clears fromName/replyTo (system templates only, 409 otherwise); DELETE refuses system templates (409). Every write records email_template.created|updated|deleted with the template view as data.

From name and reply-to. replyTo overrides your store's verified sender as the Reply-To header. fromName (1–100 characters; line breaks and "<> are stripped) replaces the display name on the message — the address itself is never the caller's to choose.

Preview. POST …/preview { eventId? } renders against that event or, without one, the built-in sample for the template's kind (order, product, customer, cart, statement or return; §4) → { subject, bodyHtml, bodyText, errors: [{ field, error, position }], event: { id, type, occurredAt } | null, sample, template: { id, key, fromName, replyTo } }. Buyer-controlled strings are escaped in bodyHtml.

3. The template language

A small language of Formahand's own: no eval, no arbitrary code, and the same implementation everywhere, so what a preview shows is exactly what a run sends. describe_flows returns the grammar, the helper list and the context below, so an agent can write a template without reading this page. A syntax error is reported with a 0-based position, never thrown at send time.

template    := (text | tag)*
tag         := "{{" expression "}}"                 output, HTML-escaped in html mode
             | "{{{" path "}}}"                     unescaped only when path is in the raw allow-list, else escaped
             | "{{!" comment "}}"                   dropped
             | "{{#if" expression "}}" template ("{{else}}" template)? "{{/if}}"
             | "{{#unless" expression "}}" template ("{{else}}" template)? "{{/unless}}"
             | "{{#each" expression "}}" template ("{{else}}" template)? "{{/each}}"
expression  := helper argument* | argument
argument    := path | literal | "(" expression ")"
helper      := money | date | upper | lower | default | link | join | length | eq | ne | gt | lt | gte | lte | not | and | or
literal     := string | number | "true" | "false" | "null"
string      := "..." or '...' with escapes \" \' \\ \n \t
number      := integer or decimal, optionally negative (-3, 2.5)
path        := root ("." segment | "[" integer "]")*
root        := identifier | this | @index | @first | @last
segment     := identifier | integer                (data.items.0.sku == data.items[0].sku)

Semantics: whitespace inside tags is optional; null/undefined render as ""; numbers and booleans as text; arrays and objects as JSON. #if/#unless use JavaScript truthiness except that empty arrays are false. #each iterates arrays only (anything else takes the {{else}} branch); inside, bare paths resolve against the current item first, then enclosing items, then the root, and {{this}}, {{@index}} (0-based), {{@first}}, {{@last}} are available. A line holding only whitespace and one block tag or comment is removed entirely (the Mustache standalone rule), so text bodies stay tidy. Helpers are pure, take positional arguments and nest with parentheses.

Security and limits: lookups use own properties only; the segments __proto__, constructor and prototype always resolve to undefined; arrays accept only integer segments; {{ }} output is escaped (& < > " ') in html mode; {{{ }}} is unescaped only for a bare path on the raw allow-list, and nothing is on that list today, so it behaves like {{ }}; link is the only helper that emits markup. 65 536 source characters, 16 nested blocks, 10 000 loop iterations per render, 262 144 output characters. Errors carry a 0-based position: Unclosed block {{#if}} opened at position N, Unexpected {{/each}}, Unknown helper \x\, Template is too long (max 65536 characters), Block nesting is too deep (max 16). Subjects are rendered in text mode and collapsed to one line; HTML bodies in html mode; text bodies in text mode, then runs of three or more newlines become two.

4. The context

What a template — or any string field of an action — is rendered against:

store:    { name, url, hostname, supportEmail, paymentInstructions }
          -- url = https://<your primary hostname> ("" without one); supportEmail = your verified sender or "";
          -- paymentInstructions = the payment instructions you saved
event:    { id, type, occurredAt, actor, resource, resourceId }
data:     the object after the write (the event's data), enriched for orders (below)
previous: { field: previous value } for the changed fields
changed:  ["trackingStatus", …]
links:    { store, tracking, carrierTracking, order, dashboard, unsubscribe }
          -- tracking = the buyer tracking page, else the carrier's page; order = https://formahand.com/dashboard?order=<id>
          -- (order events only); dashboard = https://formahand.com/dashboard; unsubscribe = "" (reserved)
merchant: { email }   -- the store owner's address, "" when Formahand has none

When event.resource is order, the order is enriched (never overwriting an existing field) with: label (#1042 or ""), items[i].lineTotalMinor (unitPriceMinor × quantity), addressLines (["1 Loop Road", "Portland, OR, 97201", "US"]), shipToName (shippingName else customerName), discountLabel (Discount (WELCOME10) / Discount), shippingLabel (Shipping (Standard) / Shipping), hasShipping (shippingMinor || shippingMethod), trackingLink (trackingPageUrl else the carrier URL) and carrierTrackingUrl (the typed trackingUrl else the carrier's page). Order fields otherwise are the order detail GET /api/orders?orderId=<id> returns (events), including tags. Products and customers are their GET /api/products / GET /api/crm/contacts views.

Samples: a sample order (#1042, Ada Buyer, two items, a discount, USPS, delivered), a sample product (Granola, inventory 2, previously 4), a sample customer and a sample cart, each shaped like an event view with id: "SAMPLE". A preview picks the sample by the template's declared kind; a dry run picks it by the flow's first concrete topic and uses that topic as the sample's type.

5. Flows

A flow:

{ "name": "Delivered → thank-you email", "enabled": true,
  "topics": ["order.delivered"], "filter": "",
  "actions": [{ "type": "send_email", "template": "order-delivered", "to": "buyer" }] }

• Limits. 20 flows per store (409), 1–20 topics, name 1–80, filter ≤ 1000 characters, 1–10 actions.
• Topics and filter are the subscription vocabulary and predicate language of events §4–5, validated the same way (400 { error, field: "filter", position }).
• Actions run in order. Every string field is a template rendered in text mode against the context of §4; when is an optional per-action predicate (same grammar as filter; false → the action is skipped with when: false).

A personal code after purchase is two steps: { "type": "issue_code", "template": "COMEBACK", "expiresInDays": 30, "bindToCustomer": true } then { "type": "send_email", "template": "come-back", "to": "buyer" }, with {{ issued.code }} in the template. The same on customer.created gives every new customer a welcome code of their own.

to and cc accept, comma-separated: buyer (data.customerEmail, else data.email), merchant (the store owner's address), a literal address, or a template such as {{ data.customerEmail }}; anything that does not render to an address is reported in the skip detail. Secrets (secret, bearer) are stored with the flow like a subscription's target, shown as secretSet / bearerSet in every view and event, and kept when an update omits them for an action of the same type at the same position.

How a run goes. A run that can no longer find its flow or its event is failed with missing. With the store's kill switch off the run stays pending with error = flows_disabled, is looked at again ten minutes later, and spends no attempt. Otherwise each action is prepared (predicate, rendering, recipient resolution, template render) and then performed, and the result is one entry of the run's result:

{ "actions": [{ "index": 0, "type": "send_email", "status": "queued", "to": ["ada@example.com"], "mailIds": ["…"], "detail": "1 email(s) handed over for sending" },
              { "index": 1, "type": "add_order_note", "status": "done", "detail": "note appended" }],
  "depth": 1, "actor": "system:flow:<flow id>:1" }

Statuses: done, skipped (with detail), failed (with error), queued (email handed over, waiting for the answer from the mail service). A run with no failed action is delivered; the flow's runCount, lastRunAt and lastStatus = ok are updated and its failure counter reset. Any failed action puts the run back on the schedule (pending with the next backoff step, failed once exhausted) with error = "action N (type): <error>; …", and increments the flow's failure counter. A retry re-runs only the actions that failed: entries that are done, skipped or queued are carried over from the previous result. When an email is rejected, that action flips to failed (mail_failed: …), a delivered run goes back to pending on the same schedule and the flow's failure counter moves — so an outage at the mail service delays email and never duplicates a note, a tag or a webhook. Sent mail flips the action to done with its messageIds.

Delays are a step, not a separate flow. A run that reaches a wait records the step and the moment it should carry on, and stops there; it is picked up when the wait is over, so the delay survives a restart or an upgrade and costs no attempt (§20). Modelling a delay as a second flow on a later event still works and is cheaper when a real event (order.delivered, cart.abandoned) already marks the moment.

6. Guardrails

Worked loop example. Flow A tags every order.updated with a; flow B appends a note on every order.updated. A merchant edits a note (event E0, actor the user): A and B run at depth 1. A's tag write records E1 (actor system:flow:A:1); B's note write records E2 (system:flow:B:1). A skips E1 (its own) and runs on E2 at depth 2, but the tag is already present, so nothing is written; B skips E2 and runs on E1 at depth 2, appending again (E3, system:flow:B:2). A runs on E3 at depth 3 (no change, no event). Had it written, its event would carry depth 3 and trigger nothing. Five runs, then silence.

7. Recipes

Recipes (GET /api/flows/recipes, also returned by describe_flows). Each is a complete flow an agent can pass to create_flow unchanged, plus placeholders: [{ path, description, example }] for the values worth changing.

Formahand already sends the shipping email when you tick "notify customer"; shipped-tracking-email sends it on every fulfilment regardless. new-customer-welcome fails validation until the welcome template exists (actions.0.template).

8. API and MCP

Routes take ?storeId= on GET/DELETE and storeId in JSON bodies for sessions; a token is bound to its store. Errors are { error, field?, position? }; field is name, topics, filter, actions, actions.<i>.<field> or a template field.

FlowView: { id, name, enabled, topics, filter, actions: [action with secretSet/bearerSet], schedule, nextRunAt, runCount, runs7d, lastRunAt, lastStatus, failureCount, disabledReason, readiness, createdAt, updatedAt } (readiness and runs7d on list and single reads, §18). EmailTemplateView: { id, key, name, description, subject, bodyHtml, bodyText, fromName, replyTo, variables, isSystem, isModified, createdAt, updatedAt }.

MCP tools (the token is the actor):

describe_events carries an automations field pointing at describe_flows.

9. Dashboard

Automations is a top-level module that opens as a hub of five tiles: Flows, Email templates, Inbound URLs, Webhooks and Events. Each opens one part with "← Automations", and the address carries it: #automations/flows, /templates, /hooks, /subscriptions, /events (the older words webhooks, email-templates and inbound land on the same parts).

• Flows (#automations/flows): the list (name, one status word — Ready · Needs setup · Paused · Error — trigger, runs, Pause/Resume on the row), New flow, Start from a recipe (#automations/flows/recipes: "Use recipe" prefills the editor and lists the placeholders to fill in, connectors below), and the kill switch as a row under the list ("Run flows"; turning it off asks first). One flow is its own page, #automations/flows/<id>, with three pills: What it does (the gate of §18 with a line per requirement and a button to the page or the check that finishes it, the ordered steps, and the dry run of §19), Runs (§21, with the schedule's own ticks under it) and Settings (trigger, condition, schedule, run counts, Edit, Delete in a dialog). Enable goes through the gate, so a flow that is not ready opens on its checklist instead of failing later. The editor (#automations/flows/new, or Edit on a flow) is four steps any of which can be opened at any time: When it runs (name, topics with vocabulary quick-adds, schedule), What must be true (a filter validated as you type), What it does (an ordered actions builder with type-specific fields and per-action when, move up/down, remove; a step type the editor does not know is kept as a read-only row and saved back unchanged) and Review; server errors open the step that holds the named field, and leaving with changes asks first. The Try panel (dry run against the last matching event or a given event id, per-action pills, rendered fields, a sandboxed frame of the email HTML with a text toggle) and the Runs panel (per-action results, Retry) are on the flow's page.
• Email templates (#automations/templates): the list (name, kind, key, updated) with Preview on the row; one template opens at #automations/templates/<id> (/new for a new one): name, key read-only for system templates, subject, From name, Reply-to, HTML and text bodies in monospace, an Insert a variable picker built from your store's own context that writes {{ path }} where the cursor was, and a short variables help with "Show all variables"; saving reports the variables the sample knows nothing about; Preview against the sample or an event id with errors[] inline; Reset (system + modified) and Delete (custom) ask in a dialog.
• Inbound URLs (#automations/hooks, one at #automations/hooks/<id>, new at /new): see §22.
• Webhooks and Events: the subscriptions and the feed of events.

10. Agent walkthrough

With a token carrying settings:read, settings:write, events:read and orders:write:

describe_flows                          → actions, template grammar, recipes, your template keys
list_email_templates                    → order-shipped exists (system, unmodified)
upsert_email_template { key: "order-shipped", name: "Order shipped", subject: "{{ store.name }}: {{ data.label }} is on its way",
                        bodyHtml: "…{{#each data.items}}…{{/each}}…{{ link data.trackingLink \"Track your parcel\" }}…" }   (optional)
create_flow { name: "Shipped → tracking email", topics: ["order.fulfilled"], filter: "data.trackingNumber != \"\"",
              actions: [{ type: "send_email", template: "order-shipped", to: "buyer" }] }            → { flow: { id } }
test_flow { id }                        → { matched: true, actions: [{ type: "send_email", status: "would_run",
                                            rendered: { to: ["ada@example.com"], subject: "…", bodyHtml: "…", bodyText: "…" } }] }
set_order_tracking { orderId, carrier: "USPS", trackingNumber: "9400…", notifyCustomer: false }
                                        → the write records order.updated + order.fulfilled, the run is queued and
                                          started at once, and the email goes out
list_flow_runs { id }                   → { runs: [{ status: "delivered", result: { actions: [{ status: "done", to: [...], messageIds: ["…"] }] } }] }

A queued action means the email has been handed over and its answer has not come back yet; failed with mail_failed means it was rejected and the run is back on the retry schedule.

12. Abandoned checkout

Free on every plan. A checkout that was started but not paid within 60 minutes is an abandoned cart.

1. What counts. Every ten minutes Formahand looks for orders that are still pending and unfulfilled, were started at least 60 minutes ago and are at most 7 days old, carry a customer email, and were being paid by card or PayPal — a bank-transfer or cash-on-delivery order is waiting for you, not for the shopper, and is never abandoned. Each order is claimed exactly once, so two passes can never raise the event twice. An order paid later keeps its abandoned mark; the event has already gone out.
2. The event: cart.abandoned, resource cart, resource id the order id, actor system:cron (events), data { orderId, orderNumber, customerEmail, customerName, currency, subtotalMinor, totalMinor, items[], checkoutUrl, unsubscribeUrl, createdAt, abandonedAt, paymentProvider }. checkoutUrl is https://<your primary host>/cart/recover?order=<id>&t=<token> — it rebuilds the shopper's cart from the order's active lines and lands on /cart (a wrong token lands on /cart untouched). unsubscribeUrl is https://<your primary host>/email/unsubscribe?e=<email>&t=<token>; visiting it records the unsubscribe and marks a matching customer unsubscribed. Both links are signed, so neither can be forged or guessed. A shopper who unsubscribed (or a customer already unsubscribed) still gets the order marked, but the event carries customerEmail: "", so the flow's send_email is skipped ("no recipient").
3. The default flow "Abandoned checkout → email after 1 hour" is seeded paused in every store with the fixed id <storeId>:flow:abandoned-checkout. Formahand remembers that it seeded it, so a merchant who deletes it does not get it back and one who edits it keeps the edits. Enabling is one click: Automations → Flows → Resume on the flow, or update_flow { id, enabled: true }; describe_flows lists the recipe abandoned-checkout-email as well. The template is abandoned-cart (editable), which links checkoutUrl and unsubscribeUrl.
4. Sample: previews and dry runs of cart templates and flows use the sample cart.

13. Scheduled triggers

A flow can run on a clock as well as on events. The flow keeps everything it already has — filter, actions, run log, kill switch — and gains a schedule:

{ "every": "15m" | "1h" | "6h" | "1d", "at": "08:00", "timezone": "Europe/Berlin" }

• every is the interval. Without at the runs sit on interval boundaries from the epoch (15m → :00, :15, :30, :45). With at they are anchored to that wall-clock time in timezone (UTC when none is given), so { every: "6h", at: "02:30", timezone: "Europe/Berlin" } runs at 02:30, 08:30, 14:30 and 20:30 local. The offset is recomputed at each scheduling, so a daylight-saving change moves the next run, not the stored schedule.
• Saving a schedule adds the topic schedule.tick to the flow for you. Sending schedule: null removes the schedule and leaves the topic list alone.

How a tick runs. Formahand looks for schedules that have come due every ten minutes. For each one it records an event

{ "type": "schedule.tick", "resource": "schedule", "resourceId": "<flowId>", "actor": "system:schedule",
  "data": { "flowId": "…", "scheduledFor": "2026-09-16T08:00:00.000Z", "timezone": "Europe/Berlin", "every": "1d" } }

and queues an ordinary flow run on it, then moves nextRunAt forward. A tick belongs to the flow it was raised for: no other flow, and no subscription filtering on schedule.tick, can pick up someone else's tick. Because that ten-minute pass is the clock, a run starts within ten minutes of its slot, never before it.

Budgets. Your plan decides how many schedules and scheduled runs you get.

Schedules beyond the allowance (the oldest ones stay inside it) simply never tick, and the day's allowance stops further runs until midnight UTC; nothing is deleted and no data is lost. Your sandbox is never budgeted.

Pausing. Three failed runs in a row pause the schedule: nextRunAt is cleared, the schedule is marked paused with a reason, and you get an email. The flow itself stays enabled and keeps running on store events. Saving the schedule again (dashboard, or update_flow { id, schedule }) resumes it. A tick counts as failed only once its run has exhausted its retries; a run still on the retry schedule is neither a success nor a failure yet.

Never run: in a suspended or dormant store, in a store that is not ready yet, while your flows are switched off, or for a paused flow. Those ticks are recorded as skipped and the schedule moves on.

Every tick is kept: GET /api/flows/:id/schedule-runs?limit= and list_flow_schedule_runs { id } show { id, flowId, ranAt, status: queued | ok | failed | skipped, error }, keyed by the tick's event id.

test_flow accepts schedule.tick as a sample, so a scheduled flow can be dry-run before its first slot.

14. Inbound hooks

A flow can also expose a URL another system posts to — a courier's status push, a supplier's stock feed, a script on your laptop — with no helper server in between.

POST https://formahand.com/hooks/<storeId>/<flowId>

create_flow_hook { flowId, mode } (or Automations → Inbound URLs) returns the URL and, once, a secret. The flow gains the topic hook.received and runs against

{ "type": "hook.received", "resource": "hook", "resourceId": "<flowId>", "actor": "system:hook",
  "data": { "flowId": "…", "body": { … }, "headers": { "content-type": "application/json" }, "receivedAt": "…" } }

so actions read the payload as {{ data.body.reference }} and so on.

Bearer — the caller sends the secret in a header:

curl -X POST https://formahand.com/hooks/STORE/FLOW \
  -H "Authorization: Bearer whsec_abc123…" \
  -H "Content-Type: application/json" \
  -d '{"reference":"ABC-123","status":"ready"}'

HMAC — the caller signs the body, so the secret is never sent:

BODY='{"reference":"ABC-123","status":"ready"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "whsec_abc123…" -hex | sed 's/^.* //')
curl -X POST https://formahand.com/hooks/STORE/FLOW \
  -H "X-Formahand-Signature: t=$T,v1=$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

The signed string is "<t>.<raw body>" and t must be within 5 minutes of now, which is what stops a captured request being replayed later.

Answers: 202 { ok: true, runId } (the run is queued, not finished), 400 for a body that is not JSON, 401 for a secret or signature that does not check out or a stale timestamp, 404 for an unknown store, flow or hook — and for a hook that is switched off, so a stranger cannot tell the difference — 405 for anything but POST, 413 over 64 KB, 429 over 60 requests a minute per hook.

One hook per flow. GET /api/flow-hooks (list_flow_hooks) lists them; rotate_flow_hook issues a new secret at the same URL and the old one stops working at once; set_flow_hook_enabled switches receiving without losing the secret; delete_flow_hook removes it. Only the first characters of a secret are ever listed again (secretPrefix).

In your sandbox a hook is created switched off, so a promoted or copied integration cannot start receiving before you say so; turn it on with set_flow_hook_enabled { enabled: true } or the Inbound URLs tab. The URL is the same in both environments; the flow id decides which one runs, and your live store is tried first.

15. The secrets vault

Your store keeps credentials for other people's systems in a write-only vault.

PUT /api/secrets { name, value } / set_secret stores or replaces one; GET /api/secrets / list_secrets returns names and timestamps only (createdAt, updatedAt, lastUsedAt); DELETE /api/secrets?name= / delete_secret removes one. describe_secrets explains the rules to an agent. If the vault is not available for your store yet the route answers 503 with the reason.

Where a secret may be used. Only where it leaves the store for a system you chose:

• a webhook action's url
• a webhook action's headers, e.g. { "Authorization": "Bearer {{ secrets.warehouse_api_key }}" } (up to 5 headers; the envelope's own headers cannot be overwritten)
• a wake_agent action's bearer

{{ secrets.* }} anywhere else — an email, a note, a tag, a filter — is refused when the flow is saved, with the field named. An action that refers to a secret your store does not have fails its run with missing_secret.

Redaction. A run log and a dry run keep the rendered request, with every stored value replaced by ***. lastUsedAt is the only trace a use leaves.

Encryption. A value is encrypted with AES-256-GCM before it is stored, under a key that belongs to your store and that one environment alone; only the ciphertext ever reaches your store's data. Two stores that keep the same value keep different ciphertexts. The plaintext exists for exactly one moment: it is handed to a run that needs it, for the length of that run.

Environments. Each environment has its own vault and its own key. promote_to_live and refresh_sandbox never copy secrets: set them again on the other side. A value that can no longer be decrypted is left out rather than failing the run, and the action that wanted it reports missing_secret.

17. Staff notification addresses

The store owner is the only person to: "merchant" resolves to. You can add up to five more addresses per email:

GET/PUT /api/notification-settings   { newOrderEmails, lowStockEmails }

Addresses are trimmed, lowercased, de-duplicated and format-checked; more than five, or one that is not an address, is a 400 and nothing is written. Agent tools: get_notification_settings / set_notification_settings (settings:read / settings:write). Dashboard: Email → Sending settings → Notifications.

The fan-out happens inside the flow engine: a send_email action whose template key is new-order-merchant gets newOrderEmails added to its recipients, low-stock-merchant gets lowStockEmails, and every other key gets nobody — so the seeded recipes new-order-notify-merchant and low-stock-notify-merchant and any flow you write with those templates all reach the same people, and a buyer email is never touched. The extra addresses are additions: the owner keeps receiving the email whatever the lists say, and the per-recipient hourly limit (§6) applies to each address on its own.

On by default. "New order → email me" and "Low stock → email me" are seeded switched on in every store, once per key, so an owner who deleted one does not get it back. A flow whose email goes only to merchant (or that uses notify_merchant) has no email-sender readiness requirement.

Two senders, one rule. Formahand writing to your store's own people — you, a member of your organisation, a staff notification address on new-order-merchant / low-stock-merchant, anything from notify_merchant — always comes from Formahand's own address, whether or not your store has a sender of its own. Your store writing to anyone else (buyers, shoppers) only ever goes out from your store's own sending address, never from Formahand's. Who counts as "your store's own people" is decided from your account's memberships and nothing else, so a staff address that is not on the account is still notified — from your store's own sending address, which is your verified domain when you have one and the shared store address until then (email marketing). A paused schedule is reported to the owner the same way.

**dailySummary is gone (2026-09-22).** It was a switch that saved a flag nothing read. A schedule can already fire daily (§13), but a schedule.tick event carries only flowId, scheduledFor and timezone — no figures — so a real summary needs an event carrying yesterday's numbers first. Nothing reads or writes the setting today.

18. Readiness: the gate on switching a flow on

A flow that cannot work should never be switched on to fail quietly at three in the morning. Every flow carries a readiness checklist, returned by GET /api/flows, GET /api/flows/:id, POST /api/flows/:id/readiness, list_flows, get_flow and get_flow_readiness:

{ "ready": false,
  "requirements": [
    { "id": "email-sender", "label": "An address the store's email is sent from", "done": false,
      "detail": "Verify your own sending address under Email → Sending settings; until then this store sends no email at all.",
      "href": "/dashboard#settings/email/domain", "blocking": true },
    { "id": "template:order-shipped", "label": "The email template \"order-shipped\"", "done": true, … },
    { "id": "shipping-mode", "label": "A shipping setup that reports parcels", "done": false, "blocking": false, … } ] }

ready is true when every blocking requirement is done; the rest is advice and never stands in the way.

The gate. POST /api/flows/:id/enable { enabled } (enable_flow) switches a flow on and answers 409 with the readiness when something blocking is missing; switching off is never gated. An ordinary write that asks for enabled: true is not refused — the flow is saved switched off with readiness and a notEnabled sentence in the answer, so nothing you or your agent wrote is lost and nothing half-built starts running.

Checking an address. POST /api/flows/:id/check-url { actionIndex? } (check_flow_url) sends one clearly marked request to each webhook / wake_agent step whose URL is fixed: a HEAD first, then a POST carrying { "formahand": { "check": true, … } } when HEAD is refused. Anything that is not 404 and not a 5xx counts as reached — an endpoint that demands a signature answers 401 and has still proved it is there. The outcome is kept per (flow, step); changing the URL makes the check stale and closes the gate again. The outbound rules of events apply, so a private address or one of ours is refused with the reason.

The sending address. A store that has not verified a domain of its own is not silent — its order confirmations, shipping updates and sign-in codes go out as the store over Formahand's shared store address — but **a flow's own send_email does not travel on it**. That mail is free text you wrote, to a recipient you chose, and a win-back is marketing in substance whatever header it carries; the shared address's reputation belongs to every store on it at once. So a store still on the shared address skips flow mail with reason: "own_domain_required", and email-sender keeps asking for your own verified sender (email marketing). Mail to your store's own people is unaffected, and so is Formahand's own order and shipping mail. PUT /api/flows/settings { senderFallbackAck: true } (acknowledge_sender_fallback) still records the acknowledgement and GET /api/flows still reports senderFallbackAck; it opens no gate.

19. Test runs

POST /api/flows/:id/test (test_flow { flowId | id, eventId? }) is the dry run: it picks the newest real event matching the flow's topics and filter, or the event you name, or a sample from the vocabulary when your store has neither, evaluates the filter and every when, renders every field — recipients, subjects, bodies, URLs, headers — and does nothing: no run recorded, no request, no email. Each step comes back as would_run, skipped (with the reason) or error (with the message and position). Your store's own details and its vault are supplied with the call, so a step that uses {{ secrets.name }} renders exactly as it would on a real run, with every stored value shown as ***.

In the dashboard it is on a flow's page, under What it does: the rendered email is shown in a sandboxed frame with an HTML/text toggle.

20. Delays: the wait step

{ "type": "wait", "minutes": 60 }

A wait holds the run and lets the steps after it carry on later — "wait an hour, then if the order is still unpaid, email the buyer" is a wait followed by an action with when: 'data.status == "pending"' (the recipe unpaid-after-an-hour-reminder). Up to 10 080 minutes (seven days).

• It is data, not a timer. The waiting step is recorded in the run itself with its resumeAt, and that is when the run is next due. A restart, a deploy or an upgrade changes nothing: the run is picked up when the wait is over, so it resumes within ten minutes of the moment it asked for and never before it.
• It spends no attempts. A waiting run is neither a success nor a failure: its attempt count, its earlier results and its retry schedule are untouched, and the flow's failure counter does not move.
• The data is re-read. When a run of an order event carries on after a wait, data is read from the order again, so a later when sees the order as it is then — paid, cancelled, fulfilled — rather than as it was when the event happened. changed and previous still describe the original write.
• Steps before it run once. Everything before the wait keeps its result across the resume, exactly like a retry: a note is never appended twice.
• It starts when the steps before it have come off. A step that is still failing and retrying does not eat into the delay: the wait is recorded once everything before it has succeeded.
• A dry run shows the wait as would_run with how long it would hold, and holds nothing.

21. Run history

GET /api/flows/:id/runs?limit= (list_flow_runs { flowId, limit? }) is the last runs of one flow, newest first: the triggering event and its type, the attempt, the status (pending — including a run that is waiting —, delivered, failed), the error, and every step's own outcome (done, skipped with the reason, queued, waiting with resumeAt, failed with the error, and the message ids of what was sent).

POST /api/deliveries/:id/retry (retry_flow_run { runId }) runs it again, and only the steps that failed: what was done, skipped or already handed over for sending is kept, so a retry never appends a note twice or sends an email twice. A retry resets the attempt count, so the whole schedule is available again, and the run starts straight away rather than at the next ten-minute pass.

Scheduled flows keep a second log — one row per tick — at GET /api/flows/:id/schedule-runs?limit= (list_flow_schedule_runs), shown under the flow's Runs tab.

Saving a template answers with warnings: variables the sample event has nothing for ({{ data.nonsens }}) and roots that are not part of the context at all. They are advice, never a refusal — a real event may well carry a field the sample does not. describe_flows and the template preview also return paths, every variable the context offers, which is what the dashboard's "Insert a variable" picker is built from.

22. Against Shopify Flow

What Shopify Flow has and we deliberately do not: a drag-and-drop canvas (the dashboard's list of steps is the editor), app-provided actions from a marketplace, and branching inside one flow (a per-step when and several flows do the same work with less to go wrong).

See also

• agents.md — every flow, schedule, hook and vault tool with its scope, and the governance around the token that calls them.
• recipes.md — whole integrations installed switched off, instead of building the same flow by hand.
• events.md — the log, the topic grammar and the delivery envelope flows react to.
• custom-fields.md — the typed values a flow's templates can read and a recipe can document.
• analytics.md — the numbers a nightly scheduled flow can mail you.