@zapier/microsoft-outlook-connector 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/NOTICE

@@ -0,0 +1,8 @@
+Independent, unofficial connector for Microsoft Outlook.
+
+Zapier licenses only the connector code in this package, under the Elastic
+License 2.0. Zapier grants no rights in Microsoft Outlook's API, services, data,
+schemas, documentation, or other materials, which remain the property of
+Microsoft Outlook. Microsoft Outlook and its logos are trademarks of their owner, used only to
+identify the service this connector works with. Not affiliated with, endorsed
+by, or sponsored by Microsoft Outlook.

package/NOTICE.md

@@ -0,0 +1,8 @@
+Independent, unofficial connector for Microsoft Outlook.
+
+Zapier licenses only the connector code in this package, under the Elastic
+License 2.0. Zapier grants no rights in Microsoft Outlook's API, services, data,
+schemas, documentation, or other materials, which remain the property of
+Microsoft Outlook. Microsoft Outlook and its logos are trademarks of their owner, used only to
+identify the service this connector works with. Not affiliated with, endorsed
+by, or sponsored by Microsoft Outlook.

package/README.md

@@ -1,4 +1,147 @@
 # @zapier/microsoft-outlook-connector
 
-> **Placeholder** — published to bootstrap OIDC Trusted Publisher configuration.
-> The real package is published via GitLab CI once trust is established.
+_Independent, unofficial connector for Microsoft Outlook. Not affiliated with, endorsed by, or sponsored by Microsoft Outlook. "Microsoft Outlook" is a trademark of its owner, used only to identify the service this connector works with._
+
+Agent-callable Microsoft Outlook tools that wrap the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/api/overview) v1.0 for a single user's mailbox: read and search mail, compose/send/reply/forward, organize messages (read state, flag, importance, categories, move, copy, delete), browse mail folders and attachments, manage calendar events, and manage personal contacts — 30 tools across mail, folders, categories, calendar, and contacts. Use when the user mentions Outlook, Microsoft 365 mail/calendar/contacts, or wants to send, read, search, or organize email, schedule events, or look up contacts — even if they don't name Outlook explicitly. Every call authorizes with a single OAuth 2.0 bearer token, supplied either through Zapier-managed auth or as a direct Graph access token.
+
+This connector is the same artifact across four shapes: MCP server, CLI bin, importable Node module, and an [Agent Skill](https://agentskills.io/) anchored by [`SKILL.md`](SKILL.md). Pick the shape that matches how your agent runs.
+
+## Install
+
+```bash
+# Run a tool with zero install — npx fetches the package on first use
+MICROSOFT_OUTLOOK_ACCESS_TOKEN=xxx npx @zapier/microsoft-outlook-connector run <toolName> '{ ... }' --connection env:MICROSOFT_OUTLOOK_ACCESS_TOKEN
+
+# Install as a dependency to import the tools in your own code
+npm install @zapier/microsoft-outlook-connector
+
+# Or install as an Agent Skill (https://agentskills.io)
+npx skills zapier/connectors --skill microsoft-outlook
+```
+
+Auth is one `[<resolver>:]<value>` connection string passed with `--connection`. The value is a _selector_, not the secret: `--connection zapier:<connection-id>` routes through Zapier-managed auth (recommended; no third-party secret enters the agent's environment — store the id in `MICROSOFT_OUTLOOK_ZAPIER_CONNECTION_ID` and pass `--connection "zapier:$MICROSOFT_OUTLOOK_ZAPIER_CONNECTION_ID"` if you like), and `--connection env:MICROSOFT_OUTLOOK_ACCESS_TOKEN` reads a direct token from `$MICROSOFT_OUTLOOK_ACCESS_TOKEN` (the token stays in `env`, never on argv). The `<resolver>:` prefix is optional — a bare value is claimed by the first matching resolver. See [`SKILL.md`](SKILL.md#auth) for tradeoffs and how to find a connection ID.
+
+## Tools
+
+All tools use the single connection `microsoft-outlook`. Mail and calendar tools accept an optional `mailbox` input (shared mailbox); the six event tools accept an optional `calendarId`.
+
+**Profile**
+
+| Tool    | Description                                                                     |
+| ------- | ------------------------------------------------------------------------------- |
+| `getMe` | Get the signed-in user's profile (name, email, UPN); doubles as the auth probe. |
+
+**Mail — compose & send**
+
+| Tool               | Description                                                 |
+| ------------------ | ----------------------------------------------------------- |
+| `sendMail`         | Compose and send an email in one step (returns no id).      |
+| `createDraft`      | Create a draft email; returns the draft id for `sendDraft`. |
+| `sendDraft`        | Send an existing draft by id.                               |
+| `replyToMessage`   | Reply (or reply-all) to a message and send immediately.     |
+| `createReplyDraft` | Create a draft reply (or reply-all) to edit before sending. |
+| `forwardMessage`   | Forward a message to new recipients and send immediately.   |
+
+**Mail — organize & read**
+
+| Tool               | Description                                                            |
+| ------------------ | ---------------------------------------------------------------------- |
+| `updateMessage`    | Update read state, flag, importance, or categories on a message.       |
+| `moveMessage`      | Move a message to another folder (returns a new id).                   |
+| `copyMessage`      | Copy a message into another folder, leaving the original.              |
+| `deleteMessage`    | Delete a message (moves it to Deleted Items; reversible).              |
+| `listMessages`     | List or search messages, newest first (the id-resolution entry point). |
+| `getMessage`       | Get a single message by id, including the full body.                   |
+| `listAttachments`  | List the attachments on a message.                                     |
+| `getAttachment`    | Get one attachment by id, including its base64 content.                |
+| `listMailFolders`  | List mail folders (top-level or a folder's subfolders).                |
+| `createMailFolder` | Create a mail folder (top-level or a subfolder).                       |
+| `listCategories`   | List the mailbox's category names and colors.                          |
+
+**Calendar**
+
+| Tool               | Description                                             |
+| ------------------ | ------------------------------------------------------- |
+| `listCalendars`    | List the user's calendars (resolves a `calendarId`).    |
+| `listEvents`       | List events and recurring-series masters.               |
+| `listCalendarView` | List events in a date range, expanding recurrences.     |
+| `getEvent`         | Get a single event by id (attendees, body, recurrence). |
+| `createEvent`      | Create a calendar event.                                |
+| `updateEvent`      | Update an event's fields or attendees.                  |
+| `deleteEvent`      | Delete (cancel) a calendar event.                       |
+
+**Contacts**
+
+| Tool            | Description                          |
+| --------------- | ------------------------------------ |
+| `listContacts`  | List or search personal contacts.    |
+| `getContact`    | Get a single personal contact by id. |
+| `createContact` | Create a personal contact.           |
+| `updateContact` | Update fields on a personal contact. |
+| `deleteContact` | Delete a personal contact by id.     |
+
+Run `npx @zapier/microsoft-outlook-connector run <toolName> --help` to see any tool's exact input contract + the available resolvers.
+
+## Usage
+
+```ts
+import { listMessages } from "@zapier/microsoft-outlook-connector";
+
+// Each named export is the consumer-facing (input, opts) => Promise<{ data, meta }>.
+// Pass auth as one `[<resolver>:]<value>` string.
+const { data } = await listMessages(
+  { search: "subject:invoice", limit: 5 },
+  { connection: "env:MICROSOFT_OUTLOOK_ACCESS_TOKEN" },
+);
+// data => { items: [{ id, subject, from, receivedDateTime, ... }], next_cursor? }
+```
+
+## MCP Server
+
+Add one stanza to any MCP-aware client (Claude Desktop, Cursor, Claude Code, …) to auto-discover the tools over stdio:
+
+<!-- prettier-ignore -->
+```jsonc
+// e.g. claude_desktop_config.json or .cursor/mcp.json
+{
+  "mcpServers": {
+    "microsoft-outlook": {
+      "command": "npx",
+      "args": ["@zapier/microsoft-outlook-connector", "mcp", "--connection", "zapier:<connection-id>"],
+    }
+  }
+}
+```
+
+No Zapier account? Use the `env:` resolver — point `--connection` at an env-var name and keep the token in `env`: `"args": ["@zapier/microsoft-outlook-connector", "mcp", "--connection", "env:MICROSOFT_OUTLOOK_ACCESS_TOKEN"]` with `"env": { "MICROSOFT_OUTLOOK_ACCESS_TOKEN": "xxx" }`.
+
+## When to use this
+
+- An agent needs to act on one user's Outlook mailbox: read or search mail, send/reply/forward, organize messages and folders, work with attachments, manage calendar events, or manage personal contacts.
+- You want request/response tools (call → result), addressable by id, optionally targeting a shared mailbox or a specific calendar.
+
+## When NOT to use this
+
+- **Triggers / change notifications** — there is no "watch for new mail/events" or webhook subscription here; the connector is request/response only.
+- **Large attachments (≥3 MB)** — only inline attachments under 3 MB are supported; large-file upload sessions are not.
+- **Group/shared _calendars_, distribution lists, mailbox rules, or auto-replies** — out of scope. (Shared _mailboxes_ are supported via the `mailbox` input.)
+
+## Links
+
+- [`SKILL.md`](SKILL.md) — runtime guidance for agents
+- [Microsoft Graph API reference](https://learn.microsoft.com/en-us/graph/api/overview) — the underlying vendor API
+- [Source](https://github.com/zapier/connectors/tree/main/apps/microsoft-outlook)
+
+## Legal
+
+**Scope of license.** Zapier licenses only the connector code in this package. Zapier grants no rights in Microsoft Outlook's API, services, data, schemas, documentation, or other materials, which remain the property of Microsoft Outlook. Your use of Microsoft Outlook's API is governed by your own agreement with Microsoft Outlook.
+
+**Trademarks and affiliation.** Microsoft Outlook and its logos are trademarks of their owner, used here only to identify the service this connector works with. This connector is not affiliated with, endorsed by, or sponsored by Microsoft Outlook.
+
+**Your responsibility.** This connector calls Microsoft Outlook's API using credentials you supply. You are responsible for holding a valid Microsoft Outlook account, for complying with Microsoft Outlook's API terms, developer policies, and acceptable use rules, and for the data you send and receive through it.
+
+**No warranty.** This connector is provided "as is," without warranty of any kind, and is not an official Microsoft Outlook product. Zapier is not responsible for changes Microsoft Outlook makes to its API or for any consequence of your use of Microsoft Outlook's API. See the repository LICENSE for the full disclaimer.
+
+**Forks.** You may fork and modify this connector under the Elastic License 2.0. You may state that your fork is "based on" Zapier's connector, but you may not use the "Zapier" name or logo as the name or branding of your fork, or in any way that suggests Zapier produces, endorses, or supports it.
+
+Licensed under the Elastic License 2.0. See the repository LICENSE and NOTICE.

package/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: microsoft-outlook
+description: Agent-callable Microsoft Outlook tools — read and search mail, send/reply/forward, organize messages and folders, manage calendar events, and manage contacts. Use when the user mentions Outlook, Microsoft 365 mail/calendar/contacts, or wants to send, read, search, or organize email, schedule events, or look up contacts — even if they don't name Outlook explicitly.
+license: Elastic-2.0
+compatibility: Requires Node.js 22.18+ or Bun 1.x; run `npm install` in this directory first.
+metadata:
+  title: Microsoft Outlook
+  source: https://github.com/zapier/connectors/blob/main/apps/microsoft-outlook/SKILL.md
+  zapier-app-key: MicrosoftOutlookCLIAPI
+  api-docs: https://learn.microsoft.com/en-us/graph/api/overview
+---
+
+# Microsoft Outlook
+
+_Independent, unofficial connector for Microsoft Outlook. Not affiliated with, endorsed by, or sponsored by Microsoft Outlook. "Microsoft Outlook" is a trademark of its owner, used only to identify the service this connector works with._
+
+Tools for a single user's Outlook mailbox against the [Microsoft Graph API](https://learn.microsoft.com/en-us/graph/api/overview) v1.0 (`https://graph.microsoft.com/v1.0/`): read and search mail, compose/send/reply/forward, organize messages (read state, flag, importance, categories, move, copy, delete), browse mail folders and attachments, manage calendar events, and manage personal contacts. 30 tools across profile, mail, folders, categories, calendar, and contacts. All calls authorize with one OAuth bearer token.
+
+## When to use this connector
+
+- An agent needs to **read or search mail** — list/search messages (by folder, KQL, or OData filter), read a full message, list and download attachments.
+- An agent needs to **send or reply** — compose-and-send, create a draft and send it later, reply / reply-all, or forward.
+- An agent needs to **organize mail** — mark read/unread, flag, set importance, categorize, move, copy, or delete a message; browse and create mail folders.
+- An agent needs to **work with the calendar or contacts** — list calendars, list events or a date-range view, create / update / delete events, and create / read / update / delete personal contacts.
+
+## Scripts
+
+One file per tool in [`scripts/`](scripts/); each tool's `inputSchema` / `outputSchema` (Zod) in the script file is the source of truth for its contract. All tools use the single connection `microsoft-outlook`. Mail and calendar tools accept an optional `mailbox` input to act on a shared mailbox; the six event tools accept an optional `calendarId` (resolve it via `listCalendars`).
+
+| Script                                                       | Tool name          | Connections         | Description                                                                   |
+| ------------------------------------------------------------ | ------------------ | ------------------- | ----------------------------------------------------------------------------- |
+| [`scripts/getMe.ts`](scripts/getMe.ts)                       | `getMe`            | `microsoft-outlook` | Get the signed-in user's profile (name, email, UPN). Resolves "my email".     |
+| [`scripts/sendMail.ts`](scripts/sendMail.ts)                 | `sendMail`         | `microsoft-outlook` | Compose and send an email in one step (returns no id).                        |
+| [`scripts/createDraft.ts`](scripts/createDraft.ts)           | `createDraft`      | `microsoft-outlook` | Create a draft email; returns the draft id for sendDraft.                     |
+| [`scripts/sendDraft.ts`](scripts/sendDraft.ts)               | `sendDraft`        | `microsoft-outlook` | Send an existing draft by id.                                                 |
+| [`scripts/replyToMessage.ts`](scripts/replyToMessage.ts)     | `replyToMessage`   | `microsoft-outlook` | Reply (or reply-all) to a message and send immediately.                       |
+| [`scripts/createReplyDraft.ts`](scripts/createReplyDraft.ts) | `createReplyDraft` | `microsoft-outlook` | Create a draft reply (or reply-all) to edit before sending.                   |
+| [`scripts/forwardMessage.ts`](scripts/forwardMessage.ts)     | `forwardMessage`   | `microsoft-outlook` | Forward a message to new recipients and send immediately.                     |
+| [`scripts/updateMessage.ts`](scripts/updateMessage.ts)       | `updateMessage`    | `microsoft-outlook` | Update read state, flag, importance, or categories on a message.              |
+| [`scripts/moveMessage.ts`](scripts/moveMessage.ts)           | `moveMessage`      | `microsoft-outlook` | Move a message to another folder (returns a new id).                          |
+| [`scripts/copyMessage.ts`](scripts/copyMessage.ts)           | `copyMessage`      | `microsoft-outlook` | Copy a message into another folder, leaving the original.                     |
+| [`scripts/deleteMessage.ts`](scripts/deleteMessage.ts)       | `deleteMessage`    | `microsoft-outlook` | Delete a message (moves it to Deleted Items; reversible).                     |
+| [`scripts/listMessages.ts`](scripts/listMessages.ts)         | `listMessages`     | `microsoft-outlook` | List or search messages, newest first (the id-resolution entry point).        |
+| [`scripts/getMessage.ts`](scripts/getMessage.ts)             | `getMessage`       | `microsoft-outlook` | Get a single message by id, including the full body.                          |
+| [`scripts/listAttachments.ts`](scripts/listAttachments.ts)   | `listAttachments`  | `microsoft-outlook` | List the attachments on a message.                                            |
+| [`scripts/getAttachment.ts`](scripts/getAttachment.ts)       | `getAttachment`    | `microsoft-outlook` | Get one attachment by id, including its base64 content.                       |
+| [`scripts/listMailFolders.ts`](scripts/listMailFolders.ts)   | `listMailFolders`  | `microsoft-outlook` | List mail folders (top-level or a folder's subfolders).                       |
+| [`scripts/createMailFolder.ts`](scripts/createMailFolder.ts) | `createMailFolder` | `microsoft-outlook` | Create a mail folder (top-level or a subfolder).                              |
+| [`scripts/listCategories.ts`](scripts/listCategories.ts)     | `listCategories`   | `microsoft-outlook` | List the mailbox's category names and colors.                                 |
+| [`scripts/listCalendars.ts`](scripts/listCalendars.ts)       | `listCalendars`    | `microsoft-outlook` | List the user's calendars (resolves a calendarId).                            |
+| [`scripts/listEvents.ts`](scripts/listEvents.ts)             | `listEvents`       | `microsoft-outlook` | List events and recurring-series masters.                                     |
+| [`scripts/listCalendarView.ts`](scripts/listCalendarView.ts) | `listCalendarView` | `microsoft-outlook` | List events in a date range, expanding recurrences ("what's on my calendar"). |
+| [`scripts/getEvent.ts`](scripts/getEvent.ts)                 | `getEvent`         | `microsoft-outlook` | Get a single event by id (attendees, body, recurrence).                       |
+| [`scripts/createEvent.ts`](scripts/createEvent.ts)           | `createEvent`      | `microsoft-outlook` | Create a calendar event.                                                      |
+| [`scripts/updateEvent.ts`](scripts/updateEvent.ts)           | `updateEvent`      | `microsoft-outlook` | Update an event's fields or attendees (attendees replace).                    |
+| [`scripts/deleteEvent.ts`](scripts/deleteEvent.ts)           | `deleteEvent`      | `microsoft-outlook` | Delete (cancel) a calendar event.                                             |
+| [`scripts/listContacts.ts`](scripts/listContacts.ts)         | `listContacts`     | `microsoft-outlook` | List or search personal contacts.                                             |
+| [`scripts/getContact.ts`](scripts/getContact.ts)             | `getContact`       | `microsoft-outlook` | Get a single personal contact by id.                                          |
+| [`scripts/createContact.ts`](scripts/createContact.ts)       | `createContact`    | `microsoft-outlook` | Create a personal contact.                                                    |
+| [`scripts/updateContact.ts`](scripts/updateContact.ts)       | `updateContact`    | `microsoft-outlook` | Update fields on a personal contact (array fields replace).                   |
+| [`scripts/deleteContact.ts`](scripts/deleteContact.ts)       | `deleteContact`    | `microsoft-outlook` | Delete a personal contact by id.                                              |
+
+**Always learn a script's input contract before calling it — never guess field names, casing, or types.** Run `--help` on either entrypoint — `./scripts/<script>.ts --help` or `npx @zapier/microsoft-outlook-connector run <script> --help` — which renders `inputSchema` as JSON Schema and lists the connection flag(s) and available resolvers. Guessing the payload just produces a `ZodError` and wastes a round-trip.
+
+## Output format
+
+Every script returns a `{ data, meta }` envelope (same shape across the CLI's JSON output, the imported SDK return value, and the MCP tool's `structuredContent`):
+
+- **`data`** — the script's result (the shape declared by its `outputSchema`).
+- **`meta.outputDataValidation`** — what validating `data` did:
+  - `{ skipped: false, droppedPaths: null }` — validated, nothing removed.
+  - `{ skipped: false, droppedPaths: [...], instruction }` — validated, but those paths (fields the API returned that the `outputSchema` doesn't declare) were stripped from `data`. If you need them, re-run with output validation skipped.
+  - `{ skipped: true }` — validation was bypassed; `data` is the raw, unchecked API output.
+
+**Reading dropped fields / `skipOutputDataValidation`.** To receive the raw, unvalidated result, set the single token `skipOutputDataValidation` — CLI: append `--skipOutputDataValidation`; MCP: pass `meta: { skipOutputDataValidation: true }` as a tool argument; SDK: pass `{ skipOutputDataValidation: true }` in the run options. Input validation is never skipped.
+
+**Trimming the result / `filterOutputData`.** To shrink a large result down to the fields you need, pass a jq expression that post-processes `data` — CLI: append `--filterOutputData '<jq>'`; MCP: pass `meta: { filterOutputData: "<jq>" }` as a tool argument. The jq runs against `data` only, NOT the `{ data, meta }` envelope, so write it rooted at `data` (see this script's output schema). The transformed value replaces `data`, `meta` is preserved, and the result is NOT re-validated against the output schema. The imported SDK has no `filterOutputData` option — reshape the returned `data` in code instead.
+
+## Disambiguation & refusals
+
+**Disambiguation before a write.** Before acting on a contact, event, or message you looked up by name/subject (e.g. update a contact found via `listContacts`, or reply to an event found via `listEvents`), count the **exact case-insensitive matches** on the name/subject:
+
+- **Exactly one match** — act on it. Don't over-ask; a single unambiguous match is the answer.
+- **Two or more that tie** — stop. List the tied candidates with a distinguishing field (a contact's `emailAddresses`/`companyName`, an event's `start`/`organizer`, a message's `from`/`receivedDateTime`) and ask the user which one they mean. Don't pick arbitrarily and don't write to all of them.
+
+**Unsupported operations — say so and stop; don't fake it with another tool.** This catalog deliberately does not:
+
+- **Watch for new mail or events (triggers).** There is no "notify me when an email arrives" or polling tool; the connector is request/response only. Don't simulate it with repeated `listMessages` calls and claim it's a subscription.
+- **Send attachments larger than 3 MB.** Only inline attachments under 3 MB are supported; large-file upload sessions are not. Don't claim a large file was sent.
+- **Access group / shared _calendars_ or distribution lists.** Group calendars and directory groups aren't exposed. (Shared _mailboxes_ are, via the `mailbox` input.)
+- **Permanently delete** mail (`deleteMessage` is a reversible move to Deleted Items) or manage mailbox rules, auto-replies, or focused-inbox settings.
+
+If asked for any of these, tell the user it's unsupported and stop — don't reach for an unrelated tool to approximate it.
+
+## Auth
+
+The connector needs a single Microsoft Graph **OAuth 2.0 bearer token**, resolved into the one `microsoft-outlook` connection slot. Pass auth as one connection string with `--connection [<resolver>:]<value>` (CLI / MCP) or `{ connection: "[<resolver>:]<value>" }` (imported). The value is a _selector_, not the secret. Two resolvers:
+
+- **`env:<ENV_VAR>`** — direct mode. Read a Graph access token from the named environment variable (conventionally `env:MICROSOFT_OUTLOOK_ACCESS_TOKEN`, with the token exported in `MICROSOFT_OUTLOOK_ACCESS_TOKEN`; it stays in `env`, never on argv). The token must already carry the delegated scopes the tools need (`User.Read`, `Mail.ReadWrite`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.ReadWrite`, `MailboxSettings.Read`, plus the `.Shared` variants for shared mailboxes); there is **no token refresh in this mode**, so supply a fresh token.
+- **`zapier:<connection-id>`** — Zapier-managed auth. Route through a Zapier Microsoft Outlook connection; the Zapier auth / retries / governance layer injects and refreshes the token for you. **Prerequisite: a Zapier account** (free signup at <https://zapier.com>). Find the ID with the Zapier SDK CLI: `npx @zapier/zapier-sdk-cli list-connections MicrosoftOutlookCLIAPI` (run `login` first if unauthenticated; add `--json` for machine output).
+
+Adding scopes later requires the user to reconnect — the granted scope set is fixed at connect time. If no connection is passed the script fails with an actionable error telling you to `Pass --connection [<resolver>:]<value>` and lists the resolvers in match order.
+
+## Using this skill
+
+### 0. Pre-flight and auth
+
+Run the bundled pre-flight check **once** at the start of a session to learn how to run the scripts in the current harness, then run scripts directly — reuse the result for the rest of the session. It detects a usable runtime (Node 22.18+ or Bun) and that dependencies are installed; it does **not** probe the network or auth (the scripts own that). Read `PREFLIGHT_STATUS` first — the single verdict token; `PREFLIGHT_RUNNER` names the runtime.
+
+```bash
+./preflight.sh
+```
+
+Exit `0` **READY**: follow `PREFLIGHT_RECOMMENDATION` — it gives the exact `--help` command to run next (e.g. `node /path/scripts/listMessages.ts --help`). The `--help` output renders `inputSchema` as JSON Schema, lists the connection flag(s) the script reads and every resolver each accepts, and tells you exactly what to provide. Use the runner from `PREFLIGHT_RUNNER` against the local script path — never `npx` (a sandbox that blocked the dep install may also block registry fetches). If a script call later fails with a network error, egress is blocked — recommend the user set up Zapier's remote MCP at `https://mcp.zapier.com`.
+
+Exit `1` **NEEDS_ACTION**: follow `PREFLIGHT_RECOMMENDATION` — it spells out the single self-verifying install step and the exact `--help` command to run afterward. Re-running the pre-flight to reconfirm is optional.
+
+The three invocation paths below all assume the pre-flight reported `READY`.
+
+### 1. Execute scripts directly
+
+When the agent has shell access to the installed directory, run a script file straight from `scripts/`. Each script is `chmod +x` with a Node-targeted shebang. **Run `--help` first** to read the input contract and confirm an auth resolver is ready — `--help` is the one path for both "learn the input contract" and "check auth":
+
+```bash
+# Inspect the contract + resolvers first
+./scripts/listMessages.ts --help
+
+# Then invoke (direct token — token stays in env)
+MICROSOFT_OUTLOOK_ACCESS_TOKEN=eyJ0... ./scripts/listMessages.ts '{"search":"subject:invoice"}' --connection env:MICROSOFT_OUTLOOK_ACCESS_TOKEN
+
+# Or route through a Zapier connection
+./scripts/getMe.ts '{}' --connection zapier:conn_xxx
+```
+
+Prerequisites: Node.js 22.18+ (or Bun 1.x) on `PATH`, plus `npm install` once in this directory. Pin the runtime explicitly with `node scripts/<name>.ts …` or `bun scripts/<name>.ts …` when needed — all forms run the same script body.
+
+### 2. Use the package's CLI
+
+```bash
+MICROSOFT_OUTLOOK_ACCESS_TOKEN=eyJ0... npx @zapier/microsoft-outlook-connector run listMessages '{"search":"subject:invoice"}' --connection env:MICROSOFT_OUTLOOK_ACCESS_TOKEN
+npx @zapier/microsoft-outlook-connector --help                       # all scripts
+npx @zapier/microsoft-outlook-connector run listMessages --help      # per-script schema + resolvers
+```
+
+Same scripts, different entry point. Use `bunx` when `PREFLIGHT_RUNNER` is `bun`. Some harnesses block `npx`/`bunx` — fall back to (1).
+
+### 3. Use as a recipe
+
+When no shipped script matches, read this `SKILL.md`, the [`references/`](references/) files, and the `scripts/` files as a recipe to generate custom code. Each script is one `export default defineTool({...})` from `@zapier/connectors-sdk` referencing the connection key `"microsoft-outlook"`; imitate that shape (Zod input/output schemas, `(input, ctx) => …` run body, the direct-mode auth being a Bearer token in the `Authorization` header). If you persist generated code, add a comment pointing back to this skill's source:
+
+```ts
+// Source: https://github.com/zapier/connectors/blob/main/apps/microsoft-outlook/SKILL.md
+```
+
+## API quirks worth knowing
+
+| Reference                                                                                    | Load it when                                                                                                                                                                                                                                                                 |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`references/microsoft-outlook-api-gotchas.md`](references/microsoft-outlook-api-gotchas.md) | A call errors and you need recovery guidance (401/403/404/413/429), an id stops resolving after a move, or you're unsure how paging, `search` vs `filter`, attachments (3 MB), all-day/online events, date-time + time zones, the 3-email contact cap, or categories behave. |

package/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Connector CLI entry point.
+ *
+ * When dist/cli.js is present (npm install route, or after a local build):
+ *   → delegates to the compiled CLI, works on any Node version.
+ *
+ * When dist/ is absent (git-clone route, no build step):
+ *   → handles the `build` subcommand directly (any Node version, no TS needed),
+ *     then falls through to cli.ts for all other subcommands (requires Node 22.18+
+ *     or Bun for TypeScript stripping outside node_modules).
+ *
+ * `build` subcommand: compiles the connector so that
+ *   `import { search } from "@zapier/notion-connector"` works on any Node version
+ *   even when the connector was installed from a git/file source. Invoked
+ *   automatically by the `prepare` lifecycle hook on git-clone installs.
+ *   Tries `npx tsup`, falls back to `bunx tsup`, exits 0 regardless so that
+ *   `npm install` / `pnpm install` never fails in restricted environments.
+ *
+ * Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+ * across every connector.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const dir = dirname(fileURLToPath(import.meta.url));
+
+if (process.argv[2] === "build") {
+  if (!existsSync(join(dir, "dist", "cli.js"))) {
+    // Try the locally-installed tsup binary first so module resolution for
+    // typescript (a required tsup peer) works from the connector's own
+    // node_modules. Fall back to npx/bunx for environments without a local
+    // install (e.g. fresh git-clone before npm install).
+    const localTsup = join(dir, "node_modules", ".bin", "tsup");
+    const candidates = existsSync(localTsup)
+      ? [
+          [process.execPath, [localTsup]],
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ]
+      : [
+          ["npx", ["tsup"]],
+          ["bunx", ["tsup"]],
+        ];
+    for (const [cmd, args] of candidates) {
+      const { status } = spawnSync(cmd, args, {
+        stdio: "inherit",
+        shell: true,
+        cwd: dir,
+      });
+      if (status === 0) break;
+    }
+  }
+  process.exit(0);
+}
+
+// Spawn the target as a subprocess so it runs as the entry point.
+// Dynamic import() would set import.meta.main = false, causing
+// runDispatchCli to return early without executing anything.
+const target = existsSync(join(dir, "dist", "cli.js"))
+  ? join(dir, "dist", "cli.js")
+  : join(dir, "cli.ts");
+
+const { status } = spawnSync(
+  process.execPath,
+  [target, ...process.argv.slice(2)],
+  { stdio: "inherit" },
+);
+process.exit(status ?? 1);

package/cli.ts

@@ -0,0 +1,5 @@
+import { runDispatchCli } from "@zapier/connectors-sdk";
+
+import connector from "./index.ts";
+
+await runDispatchCli(import.meta, connector);

package/connections.ts

@@ -0,0 +1,69 @@
+// Microsoft Graph authorizes every call — read or write, mail or calendar or
+// contacts — with a single OAuth 2.0 bearer token. There is no bot/user split
+// and no per-request credential switch, so one connection key
+// (`microsoft-outlook`) resolved by the standard chain (Zapier-managed first,
+// direct env-token fallback) covers the whole connector.
+//
+// On top of auth, every request carries `Prefer: IdType="ImmutableId"`. Outlook
+// message and event ids otherwise change when an item moves between folders,
+// which is the dominant cause of stale-id 404s; immutable ids stay stable
+// across moves, so an id captured from one call keeps working on the next.
+// Scripts that set their own `Prefer` token (plain-text bodies on getMessage,
+// a calendar timezone on calendar reads) are preserved — the wrapper appends to
+// the comma-separated Prefer list rather than overwriting it.
+
+import {
+  defineEnvResolver,
+  zapierConnectionResolver,
+} from "@zapier/connectors-sdk";
+
+const IMMUTABLE_ID_PREFER = 'IdType="ImmutableId"';
+
+/**
+ * Wrap a fetch so every request asks for immutable ids, merging with any
+ * `Prefer` token the caller already set (Prefer is a comma-separated list).
+ */
+function withImmutableId(
+  fetchImpl: typeof globalThis.fetch,
+): typeof globalThis.fetch {
+  return ((input, init = {}) => {
+    const headers = new Headers(init.headers ?? undefined);
+    const existing = headers.get("Prefer");
+    headers.set(
+      "Prefer",
+      existing ? `${existing}, ${IMMUTABLE_ID_PREFER}` : IMMUTABLE_ID_PREFER,
+    );
+    return fetchImpl(input, { ...init, headers });
+  }) as typeof globalThis.fetch;
+}
+
+/** A fetch that sends the given token as `Authorization: Bearer <token>`. */
+function bearerFetch(token: string): typeof globalThis.fetch {
+  return ((input, init = {}) => {
+    const headers = new Headers(init.headers ?? undefined);
+    headers.set("Authorization", `Bearer ${token}`);
+    return globalThis.fetch(input, { ...init, headers });
+  }) as typeof globalThis.fetch;
+}
+
+// Zapier-managed path: the Zapier auth layer injects the bearer token; we only
+// add the Prefer header on top of the resolved fetch.
+const zapierOutlookResolver = {
+  ...zapierConnectionResolver,
+  resolve: async (value: string) =>
+    withImmutableId(await zapierConnectionResolver.resolve(value)),
+};
+
+// Direct path: read a Microsoft Graph access token from the named env var and
+// send it as a Bearer header (no refresh in this mode — the runner supplies a
+// valid token), then add the Prefer header.
+const directOutlookResolver = defineEnvResolver({
+  name: "env",
+  valueDescription:
+    "env var holding a Microsoft Graph access token, sent as `Authorization: Bearer <token>`; matches when the var is set",
+  build: (token) => withImmutableId(bearerFetch(token)),
+});
+
+export const connectionResolvers = {
+  "microsoft-outlook": [zapierOutlookResolver, directOutlookResolver],
+} as const;

package/dist/cli.js

@@ -0,0 +1,4 @@
+// cli.ts
+import { runDispatchCli } from "@zapier/connectors-sdk";
+import connector from "./index.js";
+await runDispatchCli(import.meta, connector);