Outlook

An Outlook integration connects a Microsoft 365 mailbox to Mobius. Assistants can list and search what is in it, read one message or a whole conversation, open an attachment, send a message or reply in the thread, leave a draft for a person to check, mark something read, move or delete a message, and list the mailbox's folders. When mail lands in the watched folder, Mobius records a source event that a routine or trigger can react to.

A ticket email reaches the support address at 2am. You want an assistant to read it, look up the customer, and leave a drafted reply for whoever opens the queue at 8am. Outlook is the connection that makes both ends of that possible: the arrival is the event, the draft is the action.

Outlook can connect one person's mailbox or a mailbox the business owns. For that choice, and for the sign-in, consent, and disconnect rules this provider shares with the rest of the Microsoft 365 family, see Microsoft integrations.

Capability map

Connect Outlook

For delegated sign-in, Account manager defaults to You. An organization administrator can choose Your team before connecting. Either choice still acts as the Microsoft account selected on the account chooser. Connecting a second account adds a second connection rather than replacing the first, and Mobius matches reconnects by the account's Entra object ID rather than its address, so a rename or domain migration keeps the connection intact.

On connect, Mobius subscribes to the account's inbox and records where the folder stood, so a later outage has a point to catch up from. The inbox is the folder every new connection watches; you can move the watch to another folder afterwards. Actions can read any folder the account can see, but only arrivals in the watched folder raise events.

The connection finishes in Mobius for the person who started it. Returning the browser to an embedded product is currently unavailable: a connect request that includes return_url is refused with 400 embedded_return_disabled.

Your Microsoft administrator may have to approve Mobius once for the whole tenant before anyone can connect. See administrator approval.

After sign-in, open the connected mailbox and use Assistant access to grant it to selected assistants. A personal grant limits use of the mailbox and retention of its tool results to the manager's Mobius audience. A team-managed mailbox can be available to the team or named people. That audience does not restrict outbound email recipients. Adding Outlook tools to an assistant does not grant this account.

Connect a mailbox the business owns

A mailbox like support@ or billing@ belongs to the company, not to a person, and connecting it through someone's sign-in makes it theirs: it stops working when they leave. Mobius can instead connect such a mailbox on the organization's own grant, so nobody's account is in the middle of it.

In the app, the Connect the business's mailbox card on the Outlook page takes the mailbox address and an optional connection name, then opens Microsoft's admin consent screen. From the API, name the mailbox and the application plane:

{
  "auth_mode": "application",
  "mailbox": "support@northwind.example",
  "name": "Support inbox",
  "controller": { "kind": "organization" }
}

Post that to POST /v1/integrations/providers/outlook/connect and send a Microsoft Global Administrator to the returned consent URL. Four things are worth knowing before you try it:

• Your organization needs one ordinary Microsoft sign-in connection first. That is what establishes which Microsoft directory you belong to, and an app-only connection is only ever granted into a directory you have already proven.
• controller.kind must be organization, and creating this connection is an organization-admin action. The request is refused rather than quietly making it personal.
• A delegated connection cannot be converted into application authorization. Disconnect it before connecting that mailbox through the application flow.
• Only the person who started the connection can finish it. If someone else approves, Microsoft records the consent and Mobius shows them Consent recorded with a link to send back to you. Open that link while signed in to Mobius within 24 hours to finish the connection.

Add tenant_id only when your organization holds Outlook connections in more than one Microsoft tenant, so Mobius knows which directory to grant in. Mobius checks it against the tenants the organization has already proven it belongs to and never trusts it on its own.

Permissions

A person's connection requests Mail.ReadWrite, which covers reading mail, attachments, creating drafts, marking messages read, moving and deleting messages, and the change subscription. Mail.Send covers sending. User.Read is what makes the mailbox's own name and address readable for display, and offline_access is what lets the connection renew itself.

A business mailbox uses the application versions of the same two mail permissions. Those reach every mailbox in the tenant until an administrator narrows them, so scope them with Exchange RBAC for Applications.

Actions

outlook.attachment.get
outlook.attachment.list
outlook.attachment.save
outlook.conversation.get
outlook.folder.list
outlook.message.create_draft
outlook.message.delete
outlook.message.get
outlook.message.list
outlook.message.mark_read
outlook.message.move
outlook.message.send

outlook.message.list reads the inbox unless you name another folder, which takes either a well-known name such as sentitems, drafts, or archive, or a folder ID from outlook.folder.list. Bodies are left out by default because they are large; set include_body when the assistant genuinely needs them, or fetch the one message that matters with outlook.message.get. A search and a filter cannot be combined, and search wins when both are given. A call returns at most 50 messages, and 25 unless you set limit. There is no page cursor: has_more: true means more messages match, and the assistant narrows the request to see them: by date (a receivedDateTime filter), folder, or another filter. A search ignores filter, so with a search the assistant narrows the search terms instead, for example received>=2026-10-01. List and conversation items leave out folder_id; outlook.message.get returns it.

Bodies come back as plain text, which keeps a long Word-formatted email from filling the assistant's context with markup. Plain text keeps a link's words but can drop the address behind them. When the assistant needs those, call outlook.message.get with body_type: "html" for that one message.

Read the message or its conversation with outlook.conversation.get before replying when the assistant needs context beyond the subject line. It returns the thread oldest first, from both the inbox and Sent Items, so the assistant sees both sides of it.

outlook.message.send works two ways. Give it reply_to_id and it threads into that conversation, where Outlook supplies the recipients, the subject, and the quoted original, so your body is only the new prose on top. A reply keeps the body's line breaks; set body_type: "html" only when the body is already HTML. Without reply_to_id it sends a fresh message and needs both to and subject.

Every send saves a copy to Sent Items, and that isn't a choice the caller makes. Mail an assistant sends on the business's behalf has to be findable afterwards, and a send that leaves no copy is off the record.

Use outlook.message.create_draft when a person should read the mail before it goes out. The action returns the draft's web link, which opens it in Outlook.

outlook.message.send is not read-only or idempotent because a retry could send the mail again. outlook.message.delete, outlook.message.move, and draft creation also change the mailbox. These actions run without an automatic Mobius confirmation after the exact mailbox connection and assistant grant are rechecked.

Use a draft when a person should review the prose in Outlook before anybody sends it. That review is separate from Mobius's authorization to create the draft.

Attachments

outlook.message.get lists each attachment with its id, name, media type, and size. outlook.attachment.list returns the same list on its own.

outlook.attachment.get reads one attachment inside the turn. Text attachments such as CSV, JSON, and plain text come back decoded in text. Other files come back as base64 content, bounded by max_bytes with a default of 256 KiB and a ceiling of 1 MiB, and truncated says when the file was longer. Forwarded messages and links to files stored elsewhere carry a note instead of content.

outlook.attachment.save downloads one attachment and stores it in the Mobius library as a retained copy. The result carries the artifact_id. For PDF, DOCX, XLSX, and PPTX files, document_readable is true and the assistant can call mobius.document.inspect, mobius.document.read, and mobius.document.search on that ID to work with the content. Other files are available through mobius.file.read and the library page. Saving is bounded at 25 MiB.

Personal connections default to private; team-managed connections default to organization. An explicit visibility must fit the connection grant's permitted audience. Saving the same attachment with the same visibility and effective custody (the same person or team) again returns the existing artifact with existing: true; deleting that copy allows a new save. The library details show the mailbox provider, message identity, and saved time. Disconnecting the mailbox does not delete retained copies.

Events

outlook.mail.received

Sent when a message arrives in the watched folder, which is the inbox unless you changed it. Mail that Microsoft files elsewhere by rule never reaches the watched folder, so it raises no event.

The payload carries message_id, conversation_id, subject, body_preview, from, to, cc, received_at, is_read, has_attachments, attachments, web_link, and folder_id. When the message has attachments, attachments lists each one with its id, name, content_type, size, and is_inline. The full body is deliberately not on it: an event payload is a contract, and a whole message body does not belong on the event bus. Call outlook.message.get with the message_id inside the turn when the assistant needs it. Attachment bytes are never on the event either; use outlook.attachment.save or outlook.attachment.get in the turn.

One message produces one event even when it arrives twice. Microsoft resends a notification whose acknowledgement it missed, and a catch-up sweep can cover mail a notification already delivered. Both paths carry the same message ID, which is what Mobius deduplicates on.

Treat everything in the payload as text a stranger wrote. subject, body_preview, and the sender's display name are all attacker-controlled, and an assistant that acts on instructions found in them is doing what the sender asked rather than what you asked.

Choose the folder Mobius watches

Mobius subscribes to one mail folder per connection and emits outlook.mail.received when a message lands there. A new connection watches the inbox.

1. Open Build > Integrations, then choose Outlook.
2. In the Watched folder section, find the row for the mailbox you want.
3. Pick a folder, then click Save.

You can also open Account settings beside a conversation's message box and select this Outlook account. Only the account manager can change its watch. Check Currently watching and the saved confirmation after Save. Changing the watch controls notifications and does not grant mail access. When mailbox content is unavailable, the well-known Inbox, Archive, Drafts, and Sent Items choices remain available to the manager without listing private folder names.

The folder list comes from the mailbox itself, so a rule that files mail into Invoices can be the trigger instead of the inbox. From the API, call PUT /v1/integrations/providers/outlook/watched-folder:

{
  "integration_id": "int_01J8...",
  "folder": "archive"
}

folder is a folder ID or one of the names Microsoft reserves: inbox, archive, drafts, sentitems, deleteditems, junkemail. Saving replaces the Microsoft subscription, so give it a moment before expecting the first message from the new folder.

Checkpoint: the connection's card shows the folder you chose, and mail arriving there starts a turn.

Troubleshooting

The live status says the subscription expired

Microsoft expires mail subscriptions on a schedule of its own. Mobius renews each one well before that happens, but a deployment outage or an unreachable callback URL can let one lapse. A lapsed subscription cannot be extended, only replaced. The renewal runner replaces it on its next pass, within five minutes, and reconnecting does it immediately.

Mail arrived but no event was recorded

Microsoft sends a notification carrying the message's ID, and Mobius then fetches the message itself. If it was deleted in the moment between those two steps, there is nothing to fetch and nothing is recorded.

The other common cause is the folder. Only the watched folder raises events, so a message an Outlook rule moves on arrival is not an arrival there. Check the connection's card for the folder it watches, and source events for what did arrive.

Nothing arrived while Mobius was down

After a delivery gap Mobius replays the watched folder's change history from the point it last recorded, so the missed mail catches up on the next sync rather than being lost. Microsoft never resends the notifications themselves, which is why the replay exists.

One sweep replays at most 200 messages. A gap bigger than that fails the sync outright and leaves the recorded point where it was, rather than skipping past the excess and moving on. It is deliberately loud: losing mail quietly is the worse outcome. New mail still arrives normally on the replacement subscription while this is true, so what you are recovering is the gap window, and the mailbox itself is the place to read it. Tell your organization administrator or Mobius support if you see it.

Actions fail with a permission error after a successful sign-in

The account signed in, but the tenant has not consented to the mail permissions, or the account has no Exchange Online mailbox at all. Microsoft answers both the same way. Check that an administrator approved Mobius for the tenant, and that the account you picked is a licensed mailbox rather than a directory account.

A business mailbox connect is refused before the Microsoft screen opens

One of three things: your organization has no Outlook connection in that tenant yet, it has connections in several tenants and none was named, or controller was left off the body. Connect one mailbox the normal way first.

Consent succeeded, then reading the business mailbox failed

The administrator consented to the delegated permissions rather than the application ones. They are separate entries with the same names in the Entra portal. Add the application permissions and run the consent again.

already connected in delegated mode

Somebody has that mailbox connected through delegated authorization. Disconnect that connection before using the application flow. Changing a supported delegated connection to team-managed is a separate management change; it does not convert the Microsoft credential into application authorization.

Disconnecting did not sign the account out of Microsoft

That is deliberate, and it is shared with every Microsoft provider. One grant covers all of them for a given person, so revoking it here would also break that person's Outlook Calendar and OneDrive connections. Disconnecting removes the subscription and the stored credential. See one app registration, one grant per person for how to withdraw the authorization itself.

Next

• Read the shared Microsoft rules in Microsoft integrations.
• Watch files as well as mail with OneDrive.
• Inspect event payloads from the event catalog.
• Debug provider delivery with source events.
• Review dispatch and human-review boundaries in actions.
• Manage mailbox access in Connect accounts.