# How to connect Outlook to Hermes Agent (no API keys)

> Connect Outlook to Hermes with ClawLink in one click — 270 tools your AI agent can call from chat via hosted OAuth. No API keys, no manual setup.

Web version: https://claw-link.dev/hermes/outlook

Most guides for giving Hermes Agent Outlook access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Outlook setup: pair once in the browser and your always-on Hermes agent can act on Outlook for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Outlook.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Outlook** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect outlook  # connect Outlook (browser OAuth)
npx -y @useclawlink/cli actions outlook  # list available actions
npx -y @useclawlink/cli run outlook <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Outlook in the [ClawLink dashboard](https://claw-link.dev/dashboard) — a one-click OAuth approval, no API keys.

Verify the connection by asking Hermes:

> Use outlook_search_messages (or outlook_query_emails if my account is personal) to find the most recent email from Stripe in my inbox. Show me the subject and date, then use outlook_get_message for its id, and finally outlook_download_outlook_attachment for the PDF. Save it somewhere I can reach and tell me the file name.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Outlook is connected in the dashboard, that agent calls the same 270 Outlook tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Outlook MCP for Hermes

Looking for a Outlook MCP server for Hermes Agent? ClawLink connects Outlook to Hermes Agent and exposes 270 Outlook tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Outlook integration](https://claw-link.dev/openclaw/outlook) works the same way.

The search results for this query teach one of two setups: an app password and IMAP/SMTP hosts in `~/.hermes/.env`, or "register an application in Microsoft Entra ID, grant Mail.Send". Both are real routes and both are what ClawLink removes. This connection uses Microsoft's OAuth against an app that is already registered, so you approve the mailbox once in the browser and the 270 tools below work from chat: no Entra registration, no Graph scopes to pick, no admin consent to request for a personal account. The one thing to read before you connect is the account-type line: the toolset behaves differently on personal and work or school mailboxes, and the page below says which tools are affected.

## Two ways to give Hermes Agent access to Outlook

Most guides for connecting Outlook to Hermes Agent describe the built-in email gateway, which does a different job than this page sets up. Picking the wrong one is how an agent ends up auto-replying to a personal inbox.

### Email gateway (IMAP/SMTP)

Hermes Agent's native email channel signs into a mailbox with an app password and treats every incoming email as a message addressed to the agent. It replies in-thread.

- Built for a dedicated agent inbox: email your agent a task, get the answer as a reply.
- The app password grants full mailbox access, and the agent responds to incoming mail on its own. The official docs say not to point it at a personal account.
- Terminal setup: enable 2FA, generate an app password, put IMAP/SMTP hosts in the config.

### Outlook as tools (ClawLink)

ClawLink exposes Outlook to Hermes Agent as callable tools over MCP: search, read, draft, send, labels. Nothing runs on its own; the agent touches mail only when you ask.

- Safe on a personal Outlook account: access is granted on the provider's OAuth consent screen, revocable there at any time, no password shared.
- "Find the invoice from Stripe" or "draft a reply to Sarah": the agent acts on your inbox as you, on request.
- Browser setup: click Connect, approve, done.

The two combine well: a dedicated gateway inbox so you can reach your agent by email, plus ClawLink tools so it can work on your real mail. If you only want one and the goal is an agent that reads and writes email for you, tools are the right pick.

## What this Outlook integration does not do

The boundaries, so a prompt does not expect a capability outside the 270 tools.

- **No inbox automation that runs without you.** Every tool runs when the agent calls it; nothing reacts to incoming mail on its own. The IMAP/SMTP email gateway described earlier in this page is the separate feature that does that, and it belongs on a dedicated mailbox, not your personal one.
- **No tenant administration.** Creating Azure apps, granting admin consent, and managing other users' mailboxes are not tool surfaces; the connection is a delegated user grant.
- **No Teams chat.** Outlook's toolkit covers mail, calendar, and contacts. The Chat.ReadWrite scope on the connection has matching tools elsewhere in the catalog, not here.

The "best Outlook MCP server" roundup shape is a /hub comparison (Nylas, StackOne, and local COM servers are the names those lists lead with) and is deliberately not answered on this page.

## What the Hermes Agent Outlook integration can do

270 Outlook tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 270.

### 30 of 270 Outlook tools for Hermes

| Tool | What it does |
|---|---|
| **Calendar create event** `outlook_calendar_create_event` | Create a new Outlook calendar event |
| **Create contact** `outlook_create_contact` | Create a new Outlook contact |
| **Create draft** `outlook_create_draft` | Create a new draft Outlook email |
| **Get message** `outlook_get_message` | Get a specific Outlook message |
| **Get profile** `outlook_get_profile` | Get the connected Outlook user profile |
| **List calendars** `outlook_list_calendars` | List Outlook calendars |
| **List mail folders** `outlook_list_mail_folders` | List Outlook mail folders |
| **List messages** `outlook_list_messages` | List Outlook messages |
| **List user contacts** `outlook_list_user_contacts` | List Outlook contacts |
| **Query emails** `outlook_query_emails` | Query Outlook emails with filters |
| **Reply email** `outlook_reply_email` | Reply directly to an Outlook message |
| **Search messages** `outlook_search_messages` | Search Outlook messages |
| **Send email** `outlook_send_email` | Send a new Outlook email |
| **Download outlook attachment** `outlook_download_outlook_attachment` | Downloads a specific file attachment from an email message in a Microsoft Outlook mailbox; the |
| **Find meeting times** `outlook_find_meeting_times` | Suggests meeting times based on organizer and attendee availability, time constraints, and |
| **Get calendar event** `outlook_get_calendar_event` | Retrieve a specific event from a specified calendar |
| **Get calendar event attachment** `outlook_get_calendar_event_attachment` | Retrieve a specific attachment from an event within a calendar |
| **Get calendar from event** `outlook_get_calendar_from_event` | Retrieve the parent calendar that contains a specific event |
| **Get calendar from group** `outlook_get_calendar_from_group` | Retrieve a specific calendar from a calendar group in Microsoft Outlook |
| **Get calendar group** `outlook_get_calendar_group` | Retrieve the properties and relationships of a calendar group object |
| **Get calendar group calendar event extension** `outlook_get_calendar_group_calendar_event_extension` | Retrieve an open extension from a calendar event within a specific calendar group and calendar |
| **Get calendar group schedule** `outlook_get_calendar_group_schedule` | Retrieve free/busy schedule information for a specific user's calendar within a calendar group |
| **Get calendar permission** `outlook_get_calendar_permission` | Retrieve a specific calendar permission for a user's calendar |
| **Get calendar permission from calendar** `outlook_get_calendar_permission_from_calendar` | Retrieve a specific calendar permission from a user's calendar |
| **Get calendar schedule** `outlook_get_calendar_schedule` | Get free/busy schedule information for users, distribution lists, or resources |
| **Get calendar view** `outlook_get_calendar_view` | Get events ACTIVE during a time window (includes multi-day events) |
| **Get child folder message** `outlook_get_child_folder_message` | Retrieve a specific email message from a child mail folder |
| **Get child folder message content** `outlook_get_child_folder_message_content` | Get the MIME content of a message from a child mail folder |
| **Get child mail folder** `outlook_get_child_mail_folder` | Retrieve a specific child mail folder from a parent mail folder |
| **Get contact extension** `outlook_get_contact_extension` | Retrieve an open extension from a contact in Microsoft Graph |

## Example prompts

**Find an invoice and its attachment**

> Use outlook_search_messages (or outlook_query_emails if my account is personal) to find the most recent email from Stripe in my inbox. Show me the subject and date, then use outlook_get_message for its id, and finally outlook_download_outlook_attachment for the PDF. Save it somewhere I can reach and tell me the file name.

**Draft a reply, send on approval**

> Read the latest message from Sarah with outlook_get_message. Draft a reply that answers her questions and asks one clarifying question, then show me the draft. Do not call outlook_reply_email or outlook_send_email until I approve the text.

**Schedule a meeting around everyone's calendars**

> Use outlook_find_meeting_times for a 45 minute meeting next week with [email1] and [email2], excluding my calendar's busy blocks, then use outlook_calendar_create_event to book the earliest slot that works. Set the subject, add my agenda as the body, and invite both people. Show me the event link.

**Triage the inbox**

> List my unread messages with outlook_list_messages. Group them by sender and topic, and tell me which ones need an answer, which are newsletters, and which look like receipts. Draft one-line replies for the ones that need answers and show them to me before you send anything. For newsletters, do not move or delete anything yet.

## How the Outlook tools behave

Argument facts from the pinned-version schemas that decide what a prompt should ask for.

- **`outlook_search_messages` is enterprise-only.** It takes KQL syntax (from:, to:, received:, hasattachment:) and rejects personal mailboxes with a literal error. `outlook_query_emails` is the personal-account fallback: OData filters inside a single folder, up to 100 messages per request.
- **`outlook_list_messages` defaults to the inbox, top 10, minimal detail.** "Summarize my emails" without a folder or count argument returns ten messages with no bodies. Ask for a folder and a larger top, or use `outlook_query_emails` for filters.
- **`outlook_send_email` needs subject, body, and recipients.** `to_email` accepts comma-separated addresses, and attachments must be a non-empty file with a name and mimetype. The tool has no default subject or recipient for the agent to lean on.
- **Batch move and update calls cap at 20 items.** The validation error names the count, and the fix is splitting the batch, not changing tools.
- **Delete and move carry a confirmation step.** Production logs show "outlook_delete_message requires explicit confirmation before execution" and the move equivalent, so an agent will ask before either runs. Sends and drafts are not gated the same way, which is worth an approval step in the prompt.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Outlook working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Connection flow** | Register a Outlook app, configure redirect URLs, manage consent details, and reconnect users when auth settings drift. | Users connect Outlook through the hosted browser flow and ClawLink keeps the token lifecycle out of your app code. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Outlook. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Outlook actions to the runtime in a format your agent can reliably use. | 270 tools for Outlook are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Outlook to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Outlook in the browser, and the 270 tools above work from chat. There is no SDK, no config file, and no API key handling. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Outlook
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Outlook from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Outlook tools
Outlook tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Outlook call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Outlook returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### Search does not work with @hotmail.com or @outlook.com personal accounts. Please use a work or school (Microsoft 365/Enterprise) account.
This is the most common error on this integration in production, and it is architecture, not a bug: Microsoft's Graph Search API serves enterprise mailboxes only, so outlook_search_messages rejects personal accounts with this exact message. Reconnecting will not change it, because the mailbox type does not change. On a personal account, use outlook_list_messages for a folder or outlook_query_emails for server-side filters; both run on personal mailboxes. On a work or school account, search works as documented, with KQL syntax such as from:user@example.com and received: ranges.

Ask the agent to diagnose it:

```text
Run outlook_get_profile and tell me whether the account is a personal or work or school mailbox. Then recommend the correct tool for what I asked and do not retry search if the account is personal.
```

### Too many requests. Try again shortly.
This is Microsoft Graph throttling, returned as a 429, and the literal message is all it gives you. The response may also carry a Retry-After interval. It happens when the agent fires a burst of calls in one prompt, and the fix is to wait and then spread the work, not to reconnect. Batch operations help here: a move or update across several messages is one call when it fits under the 20-item batch limit, where separate per-message calls are many. If throttling repeats on every attempt, the shape of the prompt is the problem, and a narrower request with filters will succeed where a broad sweep does not.

Ask the agent to diagnose it:

```text
Report the exact status and any Retry-After value from the failed call. If the task involved many per-message calls, tell me which batch tools could replace them.
```

### Outlook returns "Id is malformed." or "The specified object was not found in the store."
Two production error codes cover this family. \{"error":\{"code":"TargetIdShouldNotBeMeOrWhitespace","message":"Id is malformed."\}\} appears when a move or copy target is empty or whitespace, which happens when the agent invents a destination folder instead of listing one. \{"error":\{"code":"ErrorItemNotFound","message":"The specified object was not found in the store."\}\} appears when the message id is a placeholder, or the message was moved or deleted after the id was captured. Both are solved by listing first: outlook_list_mail_folders returns real folder ids for moves, and outlook_list_messages returns real message ids for reads. Microsoft's ErrorInvalidIdMalformed variant of "Id is malformed." is the same shape from a different endpoint.

Ask the agent to diagnose it:

```text
List the mail folders or messages available to the connection, then retry the failing call with the real id from that response. Show me the id you are about to use before calling.
```

### List should have at most 20 items after validation, not 25 on parameter `updates`
Graph batch operations on this integration cap at 20 items, and the validation error names the count that broke it. The agent is asking to update or move more messages in one call than the API accepts. The fix is to split the batch into chunks of 20 or fewer, which means the tool runs twice, or to narrow the selection so a smaller batch does the job. This is an argument-shape error, not a connection fault.

Ask the agent to diagnose it:

```text
Split the batch into groups of 20 or fewer and run them in sequence. Report how many messages each batch covered.
```

### Outlook returns "Access is denied. Check credentials and try again." or AADSTS65001
The production string is \{"error":\{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."\}\}, and AADSTS65001 is the code the engines teach for the same family. Three causes. Account mismatch: the tool is pointed at a mailbox the connected identity does not own; run outlook_get_profile and compare. Tenant policy: a work or school tenant that restricts third-party app consent blocks the grant, and the consent screen or a 65001 error reports that an administrator must approve it, which is an action for your tenant admin, not a reconnect. Stale grant: consent was revoked or the connection expired, and reconnecting from the dashboard with the owning account restores it. One thing the guides say that does not apply here: switching the app from delegated to application permissions. That advice is for applications you register and run yourself; this connection is delegated by design, running as you, which is the whole point of the hosted flow.

Ask the agent to diagnose it:

```text
Run outlook_get_profile and tell me the mailbox the connection holds. If it is not the mailbox I meant, reconnect and re-run. Otherwise report the exact error code from the failing call.
```

### OAuth finished in the browser but the account is still missing
Try reconnecting Outlook and complete the consent flow in the same browser session. Partial OAuth approvals or switching accounts mid-flow can leave the connection incomplete.

### Is there a Hermes Agent Outlook integration?
Yes. ClawLink is the fastest way to connect Hermes to Outlook: link your Outlook account once in the browser and Hermes Agent can call the Outlook API through 270 ready-made tools — no custom code or token handling.

### How do I connect Outlook to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Outlook in the dashboard and Hermes can use it from the next message — no config files or API keys to manage.

### How long does it take to connect Outlook to Hermes Agent?
About two minutes. Sign in, click Connect next to Outlook in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Outlook up myself?
The alternative to ClawLink is usually manual OAuth app setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Outlook working from chat.

### Should I connect Outlook with an app password (IMAP) or through ClawLink?
An app password plugs a mailbox into Hermes Agent's email gateway, a chat channel where the agent replies to incoming mail, so it belongs on a dedicated inbox. ClawLink connects Outlook as tools through OAuth: the agent searches, reads, and drafts in your own account only when you ask. Use ClawLink if you want the agent working on your mail; use the gateway if you want to message your agent by email.

### Do I need to register an Azure app or handle admin consent to connect Outlook?
Not for this connection. The walkthrough the engines teach is real work: create an application in Microsoft Entra ID, configure redirect URIs, request Graph scopes like Mail.Send, and consent to them as an admin. ClawLink connects through an app that is already registered and requests a fixed scope set on the consent screen, which for a personal account you approve on the spot. The one case where approval is not instant is a work or school mailbox whose tenant requires administrator approval for third-party apps: the consent screen then reports that an admin must grant access, and the connection cannot complete until someone with that role approves it. That is Microsoft's tenant policy, not a setup step you can do around.

### Does the agent's search work on a personal @outlook.com account?
No, and the error is explicit about it: "Search does not work with @hotmail.com or @outlook.com personal accounts. Please use a work or school (Microsoft 365/Enterprise) account." Microsoft's Search API only serves enterprise mailboxes, so outlook_search_messages is a work-or-school tool. Personal accounts still get everything else: outlook_list_messages, outlook_query_emails, read, draft, reply, and send all work on personal mailboxes. If you are on a personal account and want search-like behavior, outlook_query_emails with server-side filters is the closest tool, and it searches one folder at a time.

### Is it safe to connect my personal Outlook to an AI agent?
The risk list for this question names prompt injection and over-permissioning, and both deserve a direct answer. Prompt injection: an agent that reads mail can be steered by the content of that mail, so links and instructions inside emails should be treated as untrusted input, which is worth writing into the prompt. Over-permissioning: this connection requests Mail.Read, Mail.ReadWrite, Mail.Send, Calendars, Contacts, and MailboxSettings, all listed on the consent screen, and the destructive tools that delete and move messages carry a confirmation step before they run. The grant is revocable from Microsoft's account settings without involving us, and nothing about the connection stores your password. Those are the mechanics; whether a mail-reading agent is right for your inbox is a judgment call the page cannot make for you.

### Why do I get permission errors if the connection is set up correctly?
The usual cause is account mismatch: the connection shows as healthy while the tool is pointed at a mailbox the connected identity does not own. A work or school connection cannot read a personal mailbox or a colleague's shared folder unless the shared grant exists, and the error comes back as an access-denied code rather than a clear account message. The second cause is tenant policy: some organizations restrict third-party app consent, which surfaces as an admin-approval requirement. The third is a stale grant: if consent was revoked or the connection expired, reads keep working from cache while writes fail. The fix in each case is to reconnect from the dashboard with the account that owns the mailbox and complete the consent screen, and to have the agent run outlook_get_profile first to confirm which identity the connection holds.

### What can the Hermes Agent Outlook integration actually do?
The 270 tools cover three surfaces. Mail: search, query, read, draft, reply, forward, send, move, copy, and delete, with delete and move gated by a confirmation step. Calendar: create and update events, find meeting times, free and busy schedules, and calendar permissions. Contacts: create, read, and update contacts and contact folders. The write tools are individually named in the tool list, and the ones that remove or relocate messages ask before they run.

### Hermes paired but still can't use Outlook
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [Connect Dynamics 365](https://claw-link.dev/hermes/dynamics-365) — Manage CRM and ERP data in Dynamics 365
- [Microsoft Teams tools](https://claw-link.dev/hermes/microsoft-teams) — Chat, meetings, and team collaboration
- [Connect Microsoft Excel](https://claw-link.dev/hermes/microsoft-excel) — Read and write Excel workbooks and worksheets