Automations Tools

List the current user's account functions (id, name, description, isActive, grants).

Get one account function by id — its code, grants, summary, isActive.

Create a new account function. `code` runs as a function BODY with `ctx` and `params` in scope — `export default async (params, ctx) => {…}` is also accepted; `import` is not. Params: name, description?, code?, grants?, maxRetries? (retries when run by an automation on failure; 0 = run once (default), set > 0 ONLY if the function is idempotent — safe to re-run without doubling side effects). Returns the created function (with id). ⚠️ Starts isActive:false — call updateFunction {isActive:true} before pointing a mailhook/webhook/schedule at it, or triggers will fail loudly with "target is INACTIVE". POWERS: ctx.email, ctx.env, and a site's users / entitlements are refused until the OWNER allows that power on the function's Access tab ("Powers & secrets") — you cannot grant it (grants.capabilities does nothing). When the code uses one, tell the owner to allow it there.

Update an account function — REQUIRED to change its code, grants or accessRules. Params: id, plus any of name/description/summary/code/isActive/timeout/grants/maxRetries (0 = run once; > 0 only if idempotent)/accessRules ({ execute: <condition> } — who may invoke it from outside). PUBLISHED-APP ACCESS is deny-by-default and needs BOTH: grants.bases includes the site AND accessRules.execute allows the caller (e.g. { execute: { type: "authenticated" } }); the app then calls functions.invokeAccount("<name>", params) from its frontend. Account functions use GLOBAL (account-level) env vars — ctx.env.get/set and {{VAR}} in ctx.fetch read the account store (manage via setEnvVar/listEnvVars/deleteEnvVar). DELIBERATELY SEPARATE from per-site env: site functions read site env, account functions read global env, no fallback between them. ctx.sites is keyed by display NAME, not slug (robust: Object.values(ctx.sites).find(s => s.projectId === id)); methods.call is a SERVICE CALL gated ONLY by exposed:true — the target's execute rules apply to external callers, not this path. ⚠️ New functions start isActive:false — ACTIVATE before pointing a mailhook/webhook/schedule at them.

Permanently delete an account function. Params: id.

List the account's sites + their tables/fields. Call this for exact site/table/field names before writing code.

Run an account function once (manual test). Params: id (the function id OR its exact name — e.g. "qa_echo"), event? (the input it receives as params). Returns its result and runId.

List an account function's triggers. Param: functionId. Returns { webhooks: [{id, token, isActive, lastTriggered}], schedules: [{id, cronExpression, timezone, isActive, lastTriggered, nextTrigger}] }. Its "On event" triggers: accountEvents_listEventTriggers({ targetKind: "account_function", targetRef }); its email addresses: automations_listMailhooks (targetKind account_function).

Run history of one account function, newest first: status, what started it, timing, error, log

Add a webhook trigger to an account function — a secret URL that runs it when POSTed. Param: functionId. Returns { id, token }; the URL is /api/automations/functions/webhook/<token>. The function must be Active (isActive) to actually run.

Enable or disable a webhook trigger. Params: id (webhook id), isActive (boolean).

Delete a webhook trigger. Param: id (webhook id).

Add a cron schedule trigger to an account function (event-driven — registers an in-process CronJob, no polling). Params: functionId, cronExpression (5-part "min hour day month weekday", e.g. "0 9 * * *" = 9am daily), timezone (default UTC). The function must be Active to run.

Enable or disable a schedule trigger (re-registers/unregisters the CronJob). Params: id (schedule id), isActive (boolean).

Delete a schedule trigger (unregisters its CronJob). Param: id (schedule id).

List the account's customer-owned SMTP mailboxes (Mail Accounts). Optional param "projectId" filters to mailboxes a given site may use (unbound + bound to it). Returns safe shape only — id, name, fromAddress, fromName, verified, isDefault, isActive, sentCount — NEVER credentials. sentCount is the CURRENT HOUR'S count used against hourlyLimit, not a lifetime total: it restarts at the size of the first send once an hour has passed with no send, so a drop from 8 to 1 means a new window opened, not lost history. MULTI-TENANT: one mailbox can send under several identities — ctx.email.sendVia(name, { ..., fromName }) sets the display name PER SEND (the verified address never changes), so customers sharing a mailbox each appear as themselves. ⚠️ A send returns fromNameOverridden — that means the platform PUT the name in the From header, NOT that the recipient sees it: some SMTP hosts (shared cPanel/Exim especially) rewrite From on authenticated submission to the mailbox's own configured display name, after the message leaves us and undetectably from here. If a delivered message shows the wrong name, do NOT retry or treat it as a platform bug — set the display name on the mailbox at the mail host, or use a provider allowing per-send names (SES, Postmark, Resend, Mailgun). Use these for outreach/bulk email: sends leave the owner's own domain and reputation and NO platform monthly quota applies (the built-in ctx.email.send does have a plan quota).

Add a customer-owned SMTP mailbox. Use for outreach: sends leave the customer's own domain and reputation, not the platform's shared sender, and no monthly platform quota applies.

Update a mail account. Omit password to keep the stored credential.

Delete a mail account by id. Functions calling ctx.email.sendVia with that name will start failing — check usage first.

Verify SMTP credentials (and optionally send a test email)

List the account's email triggers (Mailhooks) — each is a unique address like k3f9a2b1c7d8e9@mailhook.serenitiesai.com; any email sent or forwarded there runs its target. Optional param "projectId" also filters to hooks bound to that site. Returns { mailhooks: [{id, address, name, targetKind, targetRef, isActive, receivedCount, lastReceivedAt}] }.

Create an inbound email trigger. Returns the generated address — any email sent or forwarded to it runs the target with the parsed email as input.

Rename, retarget, or pause an email trigger. targetKind and targetRef must be sent together when retargeting.

Permanently delete an email trigger. Its address immediately stops accepting mail. Param: id.

Recent emails a mailhook received — the "did my trigger fire?" history

List GLOBAL (account-level) secrets (env vars; Automations → Secrets tab) — name, description, updatedAt. Values are NEVER returned. These are what ACCOUNT functions read via ctx.env.get / {{VAR}}; per-site env vars are a separate store (site listEnvVars).

Create or update a GLOBAL (account-level) env var. Value is encrypted at rest and never returned. Creating an EXISTING name fails unless overwrite:true — pass it only when deliberately rotating a value.

Delete a GLOBAL (account-level) env var by name. Account functions reading it will start failing — check usage first.