Skip to main content
outlook_move_email moves the email that started the task into a folder of the connected Outlook mailbox, for example Nanonets/In progress when the agent takes an invoice on and Nanonets/Processed when it is done. It changes the mailbox: it moves a message and creates folders that are missing. It never deletes anything.

​
Authentication & enablement

Any Outlook connection on the Connectors page: signed in with a Microsoft account, or an app registration set up by the customer’s IT team. The token is injected at run time and never visible to the model.
  • The connection needs the Mail.ReadWrite permission, the same one drafting needs. Signed-in connections already have it; an app registration needs Mail.ReadWrite admin-consented, and its application access policy must include the mailbox.
  • Set the tool up as one configured tool per destination, each with a fixed destination_folder: for example file_email_in_progress for Nanonets/In progress and file_email_processed for Nanonets/Processed. The agent chooses which one to call, never the folder: the tool reads its settings from its configured tool when it runs, so nothing in the call can change them, and the bare outlook_move_email refuses to run on its own.
  • If the workspace has several Outlook connections, bind each configured tool to the connection of the mailbox the trigger watches. The tool refuses to act when its connection is for a different mailbox than the one the email arrived at: an app registration’s mailbox, or a signed-in connection’s own account (read with User.Read, which signed-in connections already have). A signed-in account is compared by its primary address and sign-in name only, so a trigger recorded under one of the account’s aliases is refused.
The tool is off by default; add it to an agent explicitly.

​
Inputs

All inputs are set on the configured tool, never by the agent, and read from it when the tool runs.
  • destination_folder (required): the folder path from the top of the mailbox, with / between levels, for example Nanonets/Processed or Inbox/Nanonets/Processed. Folder names are matched as Outlook shows them. A leading Inbox or Archive that matches no top-level folder of that name is found by its system folder, so the same path works in a mailbox in any language.
  • create_missing_folders: create any folder on the path that does not exist yet, default true. With false, a missing folder is refused.
There is no message input: the tool always acts on the email that started the task, looked up from the task itself. It needs a task an Outlook email trigger started; the trigger records which email that was and the mailbox it arrived at.

​
Output

  • status is moved, or already_in_folder when the email is already there; running the tool twice for the same folder changes nothing.
  • destination_folder names the folders as Outlook does: folder names are matched ignoring case, and a leading Inbox or Archive found by its system folder shows its name in the mailbox’s language.
  • message_id is the email’s id after the move. Outlook gives a message a new id whenever it moves. A reply sent by outlook_send_email, or approved from outlook_preview_and_send, with the id the email arrived with still goes out: when Outlook no longer knows that id, the email is found again in the mailbox and the reply is sent to it.
  • from_folder names the folder the email was in, when it could be read.
  • created_folders lists the paths of folders the call created, if any, with the folders above them named as Outlook does.

​
Limits & errors

A refusal, including a 403 from Outlook, comes back to the agent as a limitation: calling the tool again gives the same answer, so the step is not retried. Any other failed call to Outlook (a timeout, a throttle, a 5xx) is an error and is retried as usual.
  • Refused destinations: the Inbox, Sent Items, Drafts, Outbox, Deleted Items and Junk Email, and anything inside Deleted Items, Junk Email, Drafts or Outbox. Subfolders of the Inbox are allowed.
  • Up to 5 folder levels; folder names up to 255 characters. A bad path is refused with the reason; fix it on the configured tool.
  • “outlook_move_email … does not run on its own” → the agent called the bare tool, which an agent without strict base tools sees beside its configured ones; it changes nothing.
  • “the configured tool sets no destination folder” → set destination_folder on the configured tool.
  • “the configured tool’s settings cannot be read” → a setting has the wrong type, for example create_missing_folders is not true or false; fix it in the tool’s configuration.
  • “configured Outlook filing capabilities could not be loaded” → the configured tool was deleted or could not be read; the call is retried, and if it keeps failing, check the agent’s tools.
  • “this task was started by …, not by an Outlook email trigger” → the task came from a person (in the app or from a chat), an eval run, a schedule, a migration comparison, another agent, an MCP client or the API. An eval run never touches a real mailbox.
  • “this task is a fork of task …” → a fork (Resume from here › Fork into a new task) copies the original task’s starting email, but it is a branch kept for comparison, often on a draft version, so it never files the email. To file it, use Resume from here › Resume in same task on the original task.
  • “this task was not started by an Outlook email” → the task came from another trigger, or was started before the triggering email was recorded.
  • “the email that started this task is in the mailbox’s Deleted Items folder; it was left there” → someone deleted it (or Outlook filed it as junk). A copy in Deleted Items or Junk Email, or in a folder inside them (for example a deleted Nanonets/In progress folder), is never moved back out, and no folder is created.
  • “the email that started this task is no longer in the mailbox” → it was deleted for good or moved to another mailbox.
  • “this tool is connected to …, but the email that started this task arrived at …” → the tool is bound to another mailbox’s connection; nothing was searched or moved.
  • “found N copies of the email” → the same message sits in several folders and the tool cannot tell which to move; nothing was moved and no folder was created.
  • “this task does not record which mailbox its email arrived at” → the tool cannot check it is filing in the right mailbox, so it does nothing.
  • A 403 names the missing permission: the connection lacks Mail.ReadWrite, or the app registration’s access policy excludes the mailbox.
  • If Outlook completes a move but its answer is lost, the tool finds the email in the destination and reports it as moved.
  • Folders created before a failed move are left in place and named in the message; the retry files into them.
  • Moving an email does not start a new task. Moving it back into the Inbox by hand does: the trigger sees it as new mail.
  • Only the email that started the task moves. Replies to emails the agent sends (for example a buyer’s answer) are separate messages and stay where they arrive.
  • One email can start tasks for several agents: when an Outlook trigger is linked to more than one agent, or several agents’ triggers watch the same mailbox. Each of those tasks files the same email, so it ends up in the folder of whichever filed it last. Give the filing tools to one of those agents, or give each agent its own folders (AP/Processed, Intake/Done).
  • Billed per call, however many folders it creates.

​
Agent Instruction Guidance

Call the configured filing tools at the points where the email’s state changes for the people reading the mailbox, for example when the agent takes the email on and when its work is finished. Leave emails the agent will not process in the Inbox: do not call the tool for them. A failed call never blocks the rest of the task; report it and carry on.