Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
Create a routine: work that runs as the authenticated user on a schedule or when activity happens in Macro, after this session ends. Returns the saved routine's id and next firing. In Macro app replies, mention the created routine as <m-document-mention>{"documentId":"ID","documentName":"NAME","blockName":"routine"}</m-document-mention>, replacing ID with the returned ID and NAME with the saved routine name. In external MCP replies, follow the MCP item-linking instructions. Do not use reminders for work that should execute, and do not create a new routine on every run of an existing one.
A routine is triggers plus steps. Pass steps as a JSON array encoded in a string.
Triggers: once (future RFC3339 time), cron (six-field expression and IANA time zone), or event (activity such as email.message_received, task.created or channel.message_posted, optionally limited to item ids and gated by a yes/no condition). Only people's actions trigger routines.
Steps run in order and a failed step stops the run:
code: TypeScript against Macro's SDK, for anything that acts or decides: labeling or archiving email, setting properties, creating tasks, posting messages, or judging items withmacro.ai.decide. See Code steps at the end.agent("Ask AI"): hand off to a model (model) or an agent from ListAgents (agent.bot_id, optionalmodeloverride): a built-in agent, or one the user owns or can use, including one on a self-hosted runtime, which need not be online to save the routine (a run it cannot serve fails and shows in ReadRoutine history). Give itinstructions, for open-ended work such as drafting, research or summarizing many items. It sees the triggering event and what earlier steps returned. A routine has at most one agent step. To schedule yourself, use your own persona id asagent.bot_id. Apps the agent needs beyond its own go inrequiredApps.
Prefer code: it is exact and cheap, and it can read many items, loop and decide. Use an agent step only for open-ended work, and put it last.
Example, label invoices as they arrive. Triggers: [{"type":"event","events":["email.message_received"]}]. Its steps string holds:
[{"type":"code","title":"Label invoices","summary":"Asks AI whether the new email is an invoice and adds the inbox's Finance label if so.","source":"export async function main({ macro, trigger }: StepContext) {\n if (trigger.kind !== 'event') return { labeled: false };\n const { probabilities } = await macro.ai.decide({\n input: { subject: trigger.item.email?.subject },\n questions: { invoice: 'Is this email an invoice or a payment request?' },\n });\n if ((probabilities.invoice ?? 0) < 0.5) return { labeled: false };\n const thread = macro.email.byId(trigger.item.entity_id);\n const inbox = (await thread.link()).id;\n for (const label of await macro.email.labels()) {\n if ((await label.linkId()) === inbox && (await label.name()) === 'Finance') {\n await thread.addLabel(label);\n return { labeled: true };\n }\n }\n return { labeled: false, missing: 'Finance' };\n}\n"}]