Skip to main content
Limited Release
Macros are in limited release and are not generally available. Contact your account manager to request access.

Macros

A macro is a reusable unit of automation that you build once and call from anywhere. Other primitives invoke a macro and pass it inputs; the macro runs its action steps in an isolated scope and returns outputs to the caller.

Use macros to share logic across hosted mailboxes, remote mailboxes, scheduled tasks, AI agents, and other macros without duplicating action steps.

What a Macro Contains​

Each macro has four parts:

PartPurpose
Name and descriptionHow the macro appears in selectors and history.
Input schemaNamed arguments the caller must (or may) provide. Supports text, number, boolean, password, and structured types.
ActionsThe ordered list of action steps the macro performs when invoked. Any action that runs in a hosted mailbox, remote mailbox, or scheduled task is also available inside a macro.
Output schemaNamed values the macro returns to its caller. The output is built from the values you store in the output namespace during the macro's actions.

Managing Macros​

Macros live under Platform → Macros at /platform/macros. From the Macros page you can:

  • Create a new macro with the New Macro button.
  • Edit a macro by selecting its name in the list.
  • Clone a macro to start a new macro from an existing one.
  • Test a macro to run it end-to-end against sample inputs without modifying live data outside the macro's own actions.
  • Delete a macro when it is no longer used. Deleted macros cannot be invoked, and any action that still references a deleted macro records an exception when it runs.

The Macros dashboard tile and the topbar Create menu also link to the Macros page so you can jump straight to the list or create a macro from anywhere in the console.

The Macro Editor​

Open a macro to edit it. The editor has three tabs:

Input​

Define the named arguments the macro accepts. Each input has:

  • A name that callers reference as {{input.name}} inside the macro's actions.
  • A type (text, number, boolean, password, object, or array).
  • An optional description that appears as help text in the caller's configuration form.
  • A required flag.

Mark sensitive inputs (API keys, secrets) as password so their values are masked in history logs.

Actions​

The ordered list of action steps the macro performs. Macros support every action that is available in hosted mailboxes, remote mailboxes, scheduled tasks, and other macros, including PSA actions, HTTP requests, AI calls, control structures, and the Invoke Macro action itself.

Reference inputs as {{input.name}}. Use {{custom.name}} for intermediate work between steps. Store final values in the output namespace by switching the Store results in variable namespace badge from custom to output on any action that produces results.

Output​

The Output tab shows the structured result the macro returns. The system derives this automatically from the macro's actions: any action whose result is stored in the output namespace contributes to the macro's output schema.

The output is what the caller sees in {{custom.<step>.<name>}} after the Invoke Macro action completes.

Calling a Macro​

Use the Invoke Macro action to call a macro from any container that supports it:

  • Hosted Mailbox rules
  • Remote Mailbox rules
  • Scheduled Tasks
  • Other Macros
  • AI Agent tools

When the Invoke Macro action runs:

  1. The system looks up the macro you selected.
  2. It opens a fresh property scope, so the macro's custom, global, input, and output variables are isolated from the caller's namespaces.
  3. It populates the macro's input namespace from the values you supplied on the action.
  4. It runs the macro's action list in order.
  5. It collects the macro's output namespace values and stores them in the Store results in variable field on the calling action.
  6. It restores the caller's variables.

This isolation lets you reuse a macro safely without worrying about variable name collisions between the caller and the macro.

Testing a Macro​

The macro detail page has a Test button that opens the shared test modal. The modal:

  • Lets you fill in sample values for each defined input.
  • Runs the full macro end-to-end against a synthetic test trigger.
  • Records the run in History under a macro_test trigger so you can inspect every step, variable value, and exception.

Use macro tests to verify a macro behaves correctly before you reference it from production rules and tasks.

Macros and AI Agents​

AI agents can call macros as tools. When you configure an agent, the Tools picker lists every macro defined for your account alongside other agents and built-in actions. Pick a macro, supply any input mappings, and the agent can invoke the macro during a conversation. The agent receives the macro's output as the tool result.

Use macros as agent tools when you want the agent to perform a specific, well-defined task (look up a customer, create a ticket, send a notification) rather than reasoning the whole task from scratch.

Variable Behavior Inside a Macro​

See Variable Namespaces for the full namespace reference. The macro-specific behavior:

  • {{input.name}} is read-only and contains the values the caller passed.
  • {{custom.name}} is the default place to store action results within the macro. It is reset between macros: a custom variable set inside the macro is not visible to the caller.
  • {{output.name}} defines the macro's return values. Values you store here become the macro's output.
  • {{global.name}} is shared with the calling email processing run when the caller is a hosted mailbox or remote mailbox. Use global sparingly.
  • {{meta.history.id}} and {{meta.history.url}} always reference the current processing run.