Invoke Macro

The Invoke Macro action runs a macro as a step inside another automation. The macro executes in an isolated scope, receives the input values you supply, and returns its output to the calling action.

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

Availability

This action is included with the Macros product. If your subscription does not include Macros, the action does not appear in the action picker. Contact your account manager to add Macros to your subscription.

When to Use This Action

Use this action when:

• You have logic (a lookup, a ticket-creation sequence, a notification) that more than one rule, task, or agent needs to run.
• You want to keep individual rules small by extracting a multi-step sequence into a reusable unit.
• You want an AI agent to perform a specific, well-defined task as a tool call.
• You want to test the same logic in isolation before wiring it into production triggers.

Don't use this action for:

• One-off logic that runs in only a single rule. Build the steps directly in the rule instead.
• Branching that only affects the current rule's flow. Use Iterate and other control structures inline.

How It Works

1. The system looks up the macro you selected by ID. If the macro was deleted, the action records an exception and stops.
2. The system opens a fresh property scope so the macro's custom, global, input, and output variables are isolated from the caller's namespaces.
3. The system renders the input values you supplied on this action and populates the macro's input namespace with the result. Inputs marked as password in the macro's input schema are masked in history logs.
4. The macro runs its action list in order. Each step has access to {{input.name}} for the values you passed in, and stores intermediate results in {{custom.name}} and final values in {{output.name}}.
5. The system collects the macro's output namespace values, restores the caller's variables, and stores the collected output in the Store results in variable field on this action.
6. A history entry is logged with the macro name and the structured output.

If the macro itself raises an exception, the calling automation receives the exception and follows your exception-handling rules.

Configuration

Field	Description
Macro	Select the macro to execute. The list shows every macro defined for your account.
Macro Inputs	Values passed into the macro's input namespace. The fields shown here come from the selected macro's input schema. Each field accepts text expressions; reference variables in the calling scope as {{custom.name}}, {{email.name}}, {{global.name}}, etc. Password-typed inputs are stored and rendered as secret values.

The Macro Inputs pane only appears after you select a macro. If you change the selected macro, the input fields rebuild to match the new macro's schema.

Returned Variables

The action stores the macro's output namespace values in the variable name you provide in Store results in variable. The shape of the result matches the macro's output schema.

For example, if the macro defines an output schema with contact and account properties and you store the result in lookup, you can reference:

Variable	Description
{{custom.lookup.contact}}	The contact value the macro stored in its output namespace.
{{custom.lookup.account}}	The account value the macro stored in its output namespace.

If the macro has no output schema, the action stores the entire output namespace from the macro run.

FAQs

What happens if the macro is deleted?

The action records the exception "Macro <name> has been deleted and cannot be executed." The calling automation receives the exception and follows your exception-handling rules. Update or replace the Macro field to point at an active macro.

Can a macro call another macro?

Yes. Invoke Macro is available as a step inside macros, so you can compose larger automations from smaller reusable units. Each nested call gets its own isolated scope.

Do macro inputs and outputs persist outside the macro?

No. The input, custom, and output namespaces are scoped to the current macro run. The caller only sees what the macro returns through its output schema, and only through the variable you set in Store results in variable.

The exception is the global namespace, which is shared with the calling email processing run when the caller is a hosted mailbox or remote mailbox. Use global sparingly.

How do I test a macro before invoking it from production?

Open the macro under Platform → Macros, select it, and use the Test button on the detail page. The shared test modal lets you supply sample inputs, runs the macro end-to-end, and records the run in History under a macro_test trigger so you can inspect every step.

Can AI agents call macros?

Yes. When you configure an AI agent, the Tools picker lists every macro alongside other agents and built-in actions. The agent invokes the selected macro using this same action under the hood.

Related Topics

• Macros: create, edit, and test reusable macros
• Variable Namespaces: how input, output, custom, and global behave inside and outside macros