> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Outlook Move Email

> File the email that started the task into a folder of the connected Outlook mailbox.

`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

```json theme={null}
{
  "tool_name": "outlook_move_email",
  "status": "moved",
  "from_folder": "In progress",
  "destination_folder": "Nanonets/Processed",
  "folder_id": "AAMkAGI2…AAA=",
  "created_folders": ["Nanonets", "Nanonets/Processed"],
  "message_id": "AAMkAGI2…BBB=",
  "internet_message_id": "<CAF3x…@mail.example.com>",
  "subject": "Invoice 902207992"
}
```

* `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.