@zapier/microsoft-outlook-connector 0.0.0 → 0.1.0

package/index.ts

@@ -0,0 +1,103 @@
+import { defineConnector, toFunctions } from "@zapier/connectors-sdk";
+
+import { connectionResolvers } from "./connections.ts";
+import copyMessageDefinition from "./scripts/copyMessage.ts";
+import createContactDefinition from "./scripts/createContact.ts";
+import createDraftDefinition from "./scripts/createDraft.ts";
+import createEventDefinition from "./scripts/createEvent.ts";
+import createMailFolderDefinition from "./scripts/createMailFolder.ts";
+import createReplyDraftDefinition from "./scripts/createReplyDraft.ts";
+import deleteContactDefinition from "./scripts/deleteContact.ts";
+import deleteEventDefinition from "./scripts/deleteEvent.ts";
+import deleteMessageDefinition from "./scripts/deleteMessage.ts";
+import forwardMessageDefinition from "./scripts/forwardMessage.ts";
+import getAttachmentDefinition from "./scripts/getAttachment.ts";
+import getContactDefinition from "./scripts/getContact.ts";
+import getEventDefinition from "./scripts/getEvent.ts";
+import getMeDefinition from "./scripts/getMe.ts";
+import getMessageDefinition from "./scripts/getMessage.ts";
+import listAttachmentsDefinition from "./scripts/listAttachments.ts";
+import listCalendarsDefinition from "./scripts/listCalendars.ts";
+import listCalendarViewDefinition from "./scripts/listCalendarView.ts";
+import listCategoriesDefinition from "./scripts/listCategories.ts";
+import listContactsDefinition from "./scripts/listContacts.ts";
+import listEventsDefinition from "./scripts/listEvents.ts";
+import listMailFoldersDefinition from "./scripts/listMailFolders.ts";
+import listMessagesDefinition from "./scripts/listMessages.ts";
+import moveMessageDefinition from "./scripts/moveMessage.ts";
+import replyToMessageDefinition from "./scripts/replyToMessage.ts";
+import sendDraftDefinition from "./scripts/sendDraft.ts";
+import sendMailDefinition from "./scripts/sendMail.ts";
+import updateContactDefinition from "./scripts/updateContact.ts";
+import updateEventDefinition from "./scripts/updateEvent.ts";
+import updateMessageDefinition from "./scripts/updateMessage.ts";
+
+const connector = defineConnector({
+  scripts: {
+    copyMessage: copyMessageDefinition,
+    createContact: createContactDefinition,
+    createDraft: createDraftDefinition,
+    createEvent: createEventDefinition,
+    createMailFolder: createMailFolderDefinition,
+    createReplyDraft: createReplyDraftDefinition,
+    deleteContact: deleteContactDefinition,
+    deleteEvent: deleteEventDefinition,
+    deleteMessage: deleteMessageDefinition,
+    forwardMessage: forwardMessageDefinition,
+    getAttachment: getAttachmentDefinition,
+    getContact: getContactDefinition,
+    getEvent: getEventDefinition,
+    getMe: getMeDefinition,
+    getMessage: getMessageDefinition,
+    listAttachments: listAttachmentsDefinition,
+    listCalendars: listCalendarsDefinition,
+    listCalendarView: listCalendarViewDefinition,
+    listCategories: listCategoriesDefinition,
+    listContacts: listContactsDefinition,
+    listEvents: listEventsDefinition,
+    listMailFolders: listMailFoldersDefinition,
+    listMessages: listMessagesDefinition,
+    moveMessage: moveMessageDefinition,
+    replyToMessage: replyToMessageDefinition,
+    sendDraft: sendDraftDefinition,
+    sendMail: sendMailDefinition,
+    updateContact: updateContactDefinition,
+    updateEvent: updateEventDefinition,
+    updateMessage: updateMessageDefinition,
+  },
+  connectionResolvers,
+});
+
+export default connector;
+export const {
+  copyMessage,
+  createContact,
+  createDraft,
+  createEvent,
+  createMailFolder,
+  createReplyDraft,
+  deleteContact,
+  deleteEvent,
+  deleteMessage,
+  forwardMessage,
+  getAttachment,
+  getContact,
+  getEvent,
+  getMe,
+  getMessage,
+  listAttachments,
+  listCalendars,
+  listCalendarView,
+  listCategories,
+  listContacts,
+  listEvents,
+  listMailFolders,
+  listMessages,
+  moveMessage,
+  replyToMessage,
+  sendDraft,
+  sendMail,
+  updateContact,
+  updateEvent,
+  updateMessage,
+} = toFunctions(connector);

package/package.json

@@ -1,7 +1,68 @@
 {
   "name": "@zapier/microsoft-outlook-connector",
-  "version": "0.0.0",
-  "description": "Placeholder published to enable OIDC Trusted Publisher setup. The real package is published via GitLab CI.",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "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",
-  "private": false
-}
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./index.ts"
+    }
+  },
+  "bin": {
+    "@zapier/microsoft-outlook-connector": "./cli.js"
+  },
+  "files": [
+    "dist/",
+    "cli.js",
+    "*.ts",
+    "scripts/",
+    "preflight.sh",
+    "SKILL.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE.md",
+    "references/",
+    "NOTICE"
+  ],
+  "dependencies": {
+    "@zapier/connectors-sdk": "^0.1.0",
+    "zod": "^4.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@zapier/zapier-sdk": ">=0.59.0 <1.0.0"
+  },
+  "keywords": [
+    "microsoft-outlook",
+    "outlook",
+    "email",
+    "calendar",
+    "contacts",
+    "microsoft-365",
+    "zapier",
+    "connector",
+    "tools",
+    "skills",
+    "mcp",
+    "agent",
+    "ai",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zapier/connectors.git",
+    "directory": "apps/microsoft-outlook"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}

package/preflight.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env sh
+# Connector pre-flight readiness check.
+#
+# Managed by @zapier/connectors-dev — do not edit; synced byte-for-byte
+# across every connector.
+#
+# Runs inside whatever agent harness installed the connector (Cursor, Claude
+# Code, Codex, Gemini CLI, Goose, ...) — often a minimal container — and answers
+# ONE question: how do I run the TypeScript scripts here? It picks a runtime —
+# Node 22.18+ when it can already resolve the connector's deps, else an explicit
+# install step (`npm install`, or `bun install` when only Bun is present) — and
+# tells the agent the exact command to run (see EXIT CODES). When deps are
+# missing it disambiguates the two sandbox failures that block an install: a
+# read-only connector dir (must run unsandboxed / be granted write) vs. a
+# blocked home dir (point the package cache inside this dir). Both surface as a
+# misleading `EPERM`, so the recommendation names the actual fix.
+#
+# NEEDS_ACTION is a single self-verifying step (install a runtime / deps), not a
+# loop: do it, then run a script. The action confirms its own success and the
+# first `--help` run is the authoritative check, so re-running this pre-flight to
+# reconfirm is optional, not required.
+#
+# THE AGENT CONTRACT IS THE STDOUT, NOT THIS HEADER. Agents don't read this file;
+# they run it and parse the `PREFLIGHT_*` lines — each value starts with a stable
+# token (parse as `KEY: (\w+)`), with an optional human gloss in parens, and
+# `PREFLIGHT_RECOMMENDATION` is the one-line next step. SKILL.md "Step 0" is the
+# agent-facing spec; this header is for maintainers of the canonical script.
+#
+# WHY POSIX sh (not bash)
+#   Minimal sandboxes often ship only BusyBox `sh` with no bash. This script runs
+#   unchanged under BusyBox sh, dash, and bash, and never hard-requires
+#   node/bun/npm — a missing runtime degrades to a NEEDS_ACTION instruction.
+#
+# EXIT CODES (the verdict; also emitted on PREFLIGHT_STATUS)
+#   0  READY         a runtime + deps are in place; run the scripts
+#   1  NEEDS_ACTION  perform the printed action (install runtime / deps), then
+#                    run a script — re-running this check is optional
+
+set -u
+
+EXIT_READY=0
+EXIT_NEEDS_ACTION=1
+
+# Directory this script lives in — deps + scripts are resolved relative to it,
+# not the caller's cwd, so `./preflight.sh` works from anywhere.
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+has() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+# Node >= 22.18 is the connector baseline (native .ts stripping). Anything older
+# is treated as "no Node" so we fall back to Bun.
+node_ge_2218() {
+  has node || return 1
+  v=$(node -v 2>/dev/null) || return 1
+  v=${v#v}
+  major=${v%%.*}
+  rest=${v#*.}
+  minor=${rest%%.*}
+  case "$major" in '' | *[!0-9]*) return 1 ;; esac
+  case "$minor" in '' | *[!0-9]*) minor=0 ;; esac
+  [ "$major" -gt 22 ] && return 0
+  [ "$major" -eq 22 ] && [ "$minor" -ge 18 ] && return 0
+  return 1
+}
+
+# Are the connector's declared deps installed where Node would find them? Node
+# won't fetch — they must be on disk (this dir's node_modules or an ancestor's).
+# Reads the connector's own package.json, so this stays connector-agnostic. A
+# bare `[ -d node_modules ]` is the wrong test: under pnpm/monorepo layouts the
+# deps can live in an ancestor (or be hoisted), and a local node_modules can
+# exist without the package being present. We check each dep's package.json
+# exists in one of Node's resolution paths rather than `require.resolve(name)`,
+# because resolving the package ENTRY can fail for ESM-only / `exports`-map
+# packages even when they're fully installed and importable.
+node_resolves() {
+  ( CDPATH= cd -- "$SCRIPT_DIR" && node -e 'const fs=require("fs"),path=require("path");const d=require("./package.json").dependencies||{};for(const k of Object.keys(d)){const ps=require.resolve.paths(k)||[];if(!ps.some(b=>fs.existsSync(path.join(b,k,"package.json"))))process.exit(1);}' ) >/dev/null 2>&1
+}
+
+# Can we actually WRITE into this directory right now? Any dep install must land
+# `node_modules/` here, so if the harness mounts the connector read-only (common
+# when skills live under ~/.<agent>/skills, outside the agent's writable
+# workspace) no install can succeed in place — the only fixes are to run it
+# unsandboxed or grant write access. Two deliberate choices:
+#   - Probe with a real create+remove, not `[ -w ]`: a sandbox denies the write
+#     at the syscall while the permission bits still look writable.
+#   - Probe by creating a DIRECTORY (`mkdir`), not a file: that's the install's
+#     very first on-disk action (node_modules/ and the cache dirs), and at least
+#     one sandbox (Claude Code) permits creating a file here while denying
+#     `mkdir` — a file-based probe reports writable and the install then EPERMs.
+dir_writable() {
+  _t="$SCRIPT_DIR/.preflight-write-test.$$"
+  mkdir "$_t" 2>/dev/null || return 1
+  rmdir "$_t" 2>/dev/null
+  return 0
+}
+
+# ---- 1) Pick a runtime -----------------------------------------------------
+# Node 22.18+ (native TS strip) is the baseline and the preferred runner whenever
+# it's present — it runs the .ts scripts directly. Bun is the fallback runner
+# only when there's no usable Node. We DON'T lean on Bun's implicit auto-install:
+# it's silently suppressed by any ancestor node_modules (monorepo layouts) and
+# fails the same way Node's `npm install` does under a sandbox that blocks Bun's
+# home cache — so missing deps are always an explicit, cache-local install step.
+nresolves=false
+node_ge_2218 && node_resolves && nresolves=true
+
+if [ "$nresolves" = true ]; then
+  runner=node
+  ready=true
+elif node_ge_2218; then
+  runner=node # present but deps unresolved — install step below
+  ready=false
+elif has bun; then
+  runner=bun # no usable Node — Bun runs the scripts; install step below
+  ready=false
+else
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  echo "PREFLIGHT_RECOMMENDATION: no Node 22.18+ or Bun found — install Node 22.18+ (ships npm) or Bun, then run \`<runner> ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 2) Install deps if the chosen runtime can't run as-is -----------------
+# Two distinct sandbox failures to disambiguate, because their fixes differ:
+#   a) This directory is READ-ONLY (skills installed outside the agent's
+#      writable workspace). No install can place node_modules here — the agent
+#      must run it unsandboxed or be granted write access. A cache flag can't
+#      help.
+#   b) The directory is writable but the HOME dir is sandboxed, so the default
+#      ~/.npm / ~/.bun cache write is what EPERMs mid-install. Pointing the cache
+#      INSIDE this directory sidesteps that without disabling the sandbox (and is
+#      harmless otherwise — just an unused cache dir).
+# So probe writability first and recommend accordingly.
+if [ "$ready" != true ]; then
+  echo "PREFLIGHT_STATUS: NEEDS_ACTION"
+  [ "$runner" = bun ] && install_cmd="bun install" || install_cmd="npm install"
+  if ! dir_writable; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed and ${SCRIPT_DIR} is read-only in the current sandbox (a test write there failed) — \`${install_cmd}\` can't place node_modules here. Run the install with the sandbox disabled, or grant the agent write access to ${SCRIPT_DIR} (a cache flag won't help — node_modules must land in this directory); then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif [ "$runner" = bun ]; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`BUN_INSTALL_CACHE_DIR=\"${SCRIPT_DIR}/.bun-cache\" bun install\` in ${SCRIPT_DIR} (the workspace-local cache survives a sandbox that blocks ~/.bun; plain \`bun install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  elif has npm; then
+    echo "PREFLIGHT_RECOMMENDATION: dependencies are not installed — run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR} (the workspace-local --cache survives a sandbox that blocks ~/.npm; plain \`npm install\` works otherwise), then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  else
+    # node >= 22.18 ships npm, so a missing npm means it was removed from the
+    # Node install. Restore it, then install with a workspace-local cache.
+    echo "PREFLIGHT_RECOMMENDATION: npm is missing (it ships with Node 22.18+) — reinstall/repair Node 22.18+, run \`npm install --cache \"${SCRIPT_DIR}/.npm-cache\"\` in ${SCRIPT_DIR}, then run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials."
+  fi
+  exit "$EXIT_NEEDS_ACTION"
+fi
+
+# ---- 3) Ready --------------------------------------------------------------
+# Runtime + deps are in place — the scripts run.
+echo "PREFLIGHT_STATUS: READY"
+echo "PREFLIGHT_RUNNER: ${runner}"
+echo "PREFLIGHT_RECOMMENDATION: run \`${runner} ${SCRIPT_DIR}/scripts/<name>.ts --help\` to discover arguments and credentials, then run the script with the required env vars set."
+exit "$EXIT_READY"

package/references/microsoft-outlook-api-gotchas.md

@@ -0,0 +1,210 @@
+# Microsoft Outlook (Microsoft Graph) — API gotchas
+
+Behavioral notes for the Outlook tools, which call the **Microsoft Graph v1.0** REST API
+(`https://graph.microsoft.com/v1.0`). Every claim here is sourced from the public Microsoft
+Graph documentation; links are inline. Load this when a call returns an error you don't
+understand, when ids stop resolving, or when paging / search / date-time handling behaves
+unexpectedly.
+
+## Authentication & identity
+
+- Every request is authorized with a single OAuth 2.0 **bearer token** (`Authorization: Bearer
+<token>`); there is no bot/user split. Use **getMe** as the auth probe — a `200` confirms the
+  connection works and returns your `id`, `displayName`, `mail`, and `userPrincipalName`.
+- Resolve **"my email"** with getMe before composing or filtering, since the signed-in user's
+  address isn't otherwise known to the tools.
+
+## Item ids change when items move — immutable ids are requested for you
+
+By default a message/event/contact **id changes when the item is moved** from one container to
+another: _"By default, this value changes when the item is moved from one container (such as a
+folder or calendar) to another."_ ([message resource](https://learn.microsoft.com/en-us/graph/api/resources/message),
+[event resource](https://learn.microsoft.com/en-us/graph/api/resources/event)) This is the dominant
+cause of stale-id `404`s.
+
+This connector sends `Prefer: IdType="ImmutableId"` on **every** request, so the ids you get back
+are stable: _"Immutable identifiers (IDs) enable your application to obtain an ID that doesn't
+change for the lifetime of the item"_ and _"will NOT change if the item is moved to a different
+folder in the mailbox."_ ([immutable ids](https://learn.microsoft.com/en-us/graph/outlook-immutable-id))
+The immutable id still changes if the item is moved to an **archive mailbox** or exported and
+re-imported (same source).
+
+- **moveMessage** returns the message in its new folder; use the id from that response for any
+  follow-up call. ([move message](https://learn.microsoft.com/en-us/graph/api/resources/message) — _"Move
+  the message to a folder. This creates a new copy of the message in the destination folder."_)
+- Ids are **case-sensitive**: _"all identifiers in Microsoft Graph, are case-sensitive."_
+  ([immutable ids](https://learn.microsoft.com/en-us/graph/outlook-immutable-id))
+- A sent message can be located in **Sent Items** by creating the draft with the immutable-id
+  header and reusing that id after sending. ([immutable ids](https://learn.microsoft.com/en-us/graph/outlook-immutable-id))
+
+## Shared mailboxes
+
+Pass a `mailbox` (UPN/email) to act on another user's mailbox via `/users/{id|userPrincipalName}`.
+This only works when that user has **shared the folder or delegated access** to the signed-in
+user: _"If Garth hasn't shared his Inbox with John, nor has he delegated his mailbox to John,
+specifying Garth's user ID or user principal name in those GET operations return an error."_
+([shared/delegated folders](https://learn.microsoft.com/en-us/graph/outlook-share-messages-folders)).
+Reading/writing a shared folder uses the `Mail.Read.Shared` / `Mail.ReadWrite.Shared` delegated
+permissions (same source). Sending **from** a shared mailbox relies on Exchange-side delegation —
+the message `sender`/`from` _"can be set to a different value when sending a message from a shared
+mailbox … or as a delegate."_ ([message resource](https://learn.microsoft.com/en-us/graph/api/resources/message))
+
+## Paging — `next_cursor` is an opaque URL
+
+List tools return `next_cursor`, which is Graph's `@odata.nextLink`. Pass it back verbatim as
+`cursor`; don't parse or rebuild it: _"Use the entire URL in the `@odata.nextLink` property in a
+GET request to retrieve the next page of results … Don't try to extract the `$skiptoken` or
+`$skip` value and use it in a different request."_ ([paging](https://learn.microsoft.com/en-us/graph/paging))
+
+- **listMessages** default page size is **10**, max **1000**: _"The default page size is 10
+  messages. Use `$top` to customize the page size, within the range of 1 and 1000."_
+  ([list messages](https://learn.microsoft.com/en-us/graph/api/user-list-messages))
+- **listCategories** is **not paged** — `masterCategories` returns the full set in one response.
+  ([list masterCategories](https://learn.microsoft.com/en-us/graph/api/outlookuser-list-mastercategories))
+
+## Search vs. filter (listMessages, listContacts, listEvents)
+
+- **`search`** is a full-text KQL query over messages. With no property prefix it searches the
+  default properties **from, subject, body**; you can also target a property (`subject:invoice`,
+  `from:acme`). Message search results are _"sorted by the date and time the message was sent"_ and
+  _"A `$search` request returns up to 1,000 results."_
+  ([$search](https://learn.microsoft.com/en-us/graph/search-query-parameter)) Because the order is
+  fixed to sent date/time, don't expect to control ordering while searching.
+- **`filter`** is an OData `$filter` for exact matches (`isRead eq false`, `importance eq 'high'`).
+  When `$filter` and `$orderby` are combined on messages, _"Properties that appear in `$orderby`
+  must also appear in `$filter`"_ and in the same order.
+  ([list messages](https://learn.microsoft.com/en-us/graph/api/user-list-messages))
+- **listContacts** filtering is **limited to email-address match**: _"You can use `$filter`, `any`,
+  and the `eq` operator on only the **address** sub-property of instances in an **emailAddresses**
+  collection. That is, you can't filter on the **name** or any other sub-property … nor can you
+  apply any other operator or function with `filter`, such as `ne`, `le`, and `startswith()`."_
+  ([list contacts](https://learn.microsoft.com/en-us/graph/api/user-list-contacts)) For name lookups,
+  list and match the returned results client-side.
+
+## Messages
+
+- **sendMail returns `202 Accepted` with no body and no message id.** _"If successful, this method
+  returns `202 Accepted` response code. It doesn't return anything in the response body"_ and
+  _"A `202 Accepted` response code … doesn't indicate that the request processing has completed.
+  Delivery of the message is subject to Exchange Online limitations and throttling."_
+  ([sendMail](https://learn.microsoft.com/en-us/graph/api/user-sendmail)) When you need the sent
+  message's id, use **createDraft** (returns the draft id) then **sendDraft**.
+- **saveToSentItems** defaults to true: _"Specify it only if the parameter is false; default is
+  true."_ (same source) Reply, reply-all, and forward also save to Sent Items.
+  ([message resource](https://learn.microsoft.com/en-us/graph/api/resources/message))
+- **createReplyDraft / forward draft** create a draft pre-populated with the original recipients
+  and quoted body that you can edit and send later: _"Create a draft to reply to the sender of a
+  message … You can update the draft later … Send the draft message in a subsequent operation."_
+  ([createReply](https://learn.microsoft.com/en-us/graph/api/message-createreply))
+- **deleteMessage is a soft delete.** The message moves to the **Deleted Items** folder —
+  _"deleteditems: The folder items are moved to when they're deleted"_ — and `deleteMessage`
+  returns `204 No Content`. A separate _"Permanently delete"_ operation purges items; this
+  connector does not expose it. ([mailFolder](https://learn.microsoft.com/en-us/graph/api/resources/mailfolder),
+  [delete message](https://learn.microsoft.com/en-us/graph/api/message-delete))
+- **updateMessage** is a PATCH: only the fields you send change. **categories REPLACE** the existing
+  set (read current via getMessage and include them to append). Subject/body are editable only on
+  drafts.
+- **bodyPreview** is _"The first 255 characters of the message body. It is in text format."_ — use
+  getMessage for the full body. ([message resource](https://learn.microsoft.com/en-us/graph/api/resources/message))
+- **getMessage** body format is controlled by `Prefer: outlook.body-content-type` (text or html);
+  this connector defaults to text. ([list messages](https://learn.microsoft.com/en-us/graph/api/user-list-messages))
+
+### Well-known folder names
+
+`folderId` / `destinationId` / `parentFolderId` accept either a folder id or a well-known name —
+_"Instead of using the corresponding folder id value, for convenience, you can use the well-known
+folder names."_ Common ones: `inbox`, `drafts`, `sentitems`, `deleteditems`, `archive`, `junkemail`.
+([mailFolder](https://learn.microsoft.com/en-us/graph/api/resources/mailfolder))
+
+## Attachments
+
+- `hasAttachments` is **false when a message has only inline attachments**: _"This property doesn't
+  include inline attachments, so if a message contains only inline attachments, this property is
+  false."_ Still call **listAttachments** to be sure. ([message resource](https://learn.microsoft.com/en-us/graph/api/resources/message))
+- An attachment is one of three kinds — a **file** (`fileAttachment`), an **item** (`itemAttachment`),
+  or a **reference** (`referenceAttachment`). ([attachment](https://learn.microsoft.com/en-us/graph/api/resources/attachment))
+- **getAttachment** returns `contentBytes` (_"The base64-encoded contents of the file"_) only for
+  **file** attachments — item and reference attachments carry no inline bytes.
+  ([fileAttachment](https://learn.microsoft.com/en-us/graph/api/resources/fileattachment))
+- **Outgoing attachments must be under 3 MB** and are sent inline (base64) in the same request:
+  _"If the file size is under 3 MB, do a single POST on the attachments navigation property … If
+  the file size is between 3 MB and 150 MB, create an upload session."_
+  ([large attachments](https://learn.microsoft.com/en-us/graph/outlook-large-attachments)) This
+  connector supports only the under-3-MB inline path; larger files (which require an upload session)
+  are not supported and surface as a `413`.
+
+## Calendar
+
+- **listEvents** returns single events **plus recurring series masters** (the recurrence
+  definition), not expanded occurrences: _"The list contains single instance meetings and series
+  masters."_ ([event resource](https://learn.microsoft.com/en-us/graph/api/resources/event))
+- **listCalendarView** expands recurring series into individual occurrences over a time window:
+  _"Get the occurrences, exceptions and single instances of events in a calendar view defined by a
+  time range."_ Its `startDateTime`/`endDateTime` are interpreted by their offset, **defaulting to
+  UTC** when none is given: _"If no timezone offset is included in the value, it is interpreted as
+  UTC."_ (`$top` range is 1–1000.) ([list calendarView](https://learn.microsoft.com/en-us/graph/api/calendar-list-calendarview))
+- **Event start/end** are `{ dateTime, timeZone }`. `dateTime` is a **naive local timestamp** in
+  the form `{date}T{time}` (e.g. `2026-07-01T15:30:00`) with **no trailing Z or offset** — the zone
+  goes in the separate `timeZone` field. `timeZone` accepts a **Windows name** (e.g. _"Pacific
+  Standard Time"_) _"as well as the other time zones supported by the calendar API"_ (IANA names
+  such as `America/Los_Angeles` are listed). ([dateTimeTimeZone](https://learn.microsoft.com/en-us/graph/api/resources/datetimetimezone))
+- **All-day events**: _"If true, regardless of whether it's a single-day or multi-day event, start,
+  and endtime must be set to midnight and be in the same time zone."_
+  ([event resource](https://learn.microsoft.com/en-us/graph/api/resources/event)) In practice `end`
+  is midnight of the day **after** the last day (so a one-day all-day event ends on the next day's
+  midnight) — shown in Microsoft Q&A examples; the API reference states only the midnight + same-zone
+  requirement.
+- **isOnlineMeeting**: set true to attach an online (Teams) meeting — _"After you set
+  isOnlineMeeting to true, Microsoft Graph initializes onlineMeeting"_ and the provider is
+  `teamsForBusiness`. ([event resource](https://learn.microsoft.com/en-us/graph/api/resources/event))
+- **updateEvent attendees REPLACE** the existing list — read current via getEvent, append, then
+  update. (PATCH sends only the fields you set.)
+- **deleteEvent** cancels the event; for meetings you organize, attendees are notified
+  (Graph exposes a _"Cancel event"_ that _"Send[s] a cancellation message from the organizer to all
+  the attendees"_). ([event resource](https://learn.microsoft.com/en-us/graph/api/resources/event))
+- Output enum values are Graph's own: `showAs` ∈ `free, tentative, busy, oof, workingElsewhere,
+unknown`; event `type` ∈ `singleInstance, occurrence, exception, seriesMaster`; `sensitivity` ∈
+  `normal, personal, private, confidential`. ([event resource](https://learn.microsoft.com/en-us/graph/api/resources/event))
+  Attendee `type` ∈ `required, optional, resource`; the attendee `status.response` is one of
+  `none, accepted, declined`, etc. ([attendee](https://learn.microsoft.com/en-us/graph/api/resources/attendee))
+
+## Contacts
+
+- A personal contact stores up to **three email addresses** — the resource exposes
+  `primaryEmailAddress`, `secondaryEmailAddress`, and `tertiaryEmailAddress`.
+  ([contact resource](https://learn.microsoft.com/en-us/graph/api/resources/contact))
+- **updateContact** array fields (`emailAddresses`, `businessPhones`) **replace** existing values —
+  read current via getContact and merge.
+- Updating other properties may auto-regenerate `displayName`: _"later updates to other properties
+  may cause an automatically generated value to overwrite the displayName value you have specified.
+  To preserve a pre-existing value, always include it as displayName."_
+  ([contact resource](https://learn.microsoft.com/en-us/graph/api/resources/contact))
+
+## Categories
+
+Categories are user-defined names in a **master list**; you apply one by assigning its
+`displayName` to an item's `categories`: _"You can apply a category to an item by assigning the
+displayName property of the category to the categories collection of the item."_ Each category's
+**color** is a preset constant (`None`, `preset0`, `preset1`, … up to 25 colors) that comes from the
+master-list entry. ([outlookCategory](https://learn.microsoft.com/en-us/graph/api/resources/outlookcategory))
+Use **listCategories** to discover the valid names. Categories are per-user (no `mailbox` option).
+
+## Errors, recovery & throttling
+
+Graph returns a JSON error envelope: a single `error` object with `code` (machine-readable) and
+`message`. _"You should only code against error codes returned in `code` properties."_
+([errors](https://learn.microsoft.com/en-us/graph/errors)) Common statuses
+([HTTP status codes](https://learn.microsoft.com/en-us/graph/errors)):
+
+| Status | Meaning                                                                                              | Recovery                                                                                      |
+| ------ | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `401`  | _"Required authentication information is either missing or not valid."_                              | Reconnect the Outlook account (token invalid/expired).                                        |
+| `403`  | _"Access is denied … The user does not have enough permission or does not have a required license."_ | Reconnect to grant the permission; shared-mailbox access also needs Exchange-side delegation. |
+| `404`  | _"The requested resource doesn't exist."_                                                            | The id may be stale — re-fetch it from the relevant list/get tool and retry.                  |
+| `413`  | _"The request size exceeds the maximum limit."_                                                      | Attachment too large — keep inline attachments under 3 MB.                                    |
+| `429`  | _"Client application has been throttled."_                                                           | Back off, then retry.                                                                         |
+
+**Throttling (`429`)**: Graph _"Returns HTTP status code 429 Too Many Requests"_ and _"Returns a
+suggested wait time in the response header of the failed request."_ Best practice: _"Wait the number
+of seconds specified in the `Retry-After` header"_ and retry.
+([throttling](https://learn.microsoft.com/en-us/graph/throttling))

package/scripts/copyMessage.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import {
+  GRAPH_BASE,
+  mailboxRoot,
+  outlookFetch,
+  parseGraphResponse,
+} from "../lib/graph.ts";
+
+const inputSchema = z
+  .object({
+    messageId: z
+      .string()
+      .describe(
+        "Message id from listMessages or another message tool. Opaque and case-sensitive; changes when the message is moved between folders.",
+      ),
+    destinationId: z
+      .string()
+      .describe(
+        "Target folder: a folder id from listMailFolders, or a well-known name (inbox, archive, deleteditems, junkemail, drafts, sentitems).",
+      ),
+    mailbox: z
+      .string()
+      .describe(
+        "Shared-mailbox address (UPN/email) to copy within instead of your own. Requires shared-mailbox delegation. Omit for your own mailbox.",
+      )
+      .optional(),
+  })
+  .strict();
+
+const outputSchema = z.object({
+  id: z.string(),
+  parentFolderId: z.string(),
+  subject: z.string(),
+});
+
+const definition = defineTool({
+  name: "copyMessage",
+  title: "Copy Message",
+  description:
+    "Copy a message into another folder, leaving the original in place. Resolve the message id via listMessages first. Returns the new copy, which has its own id distinct from the original.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}${mailboxRoot(input.mailbox)}/messages/${encodeURIComponent(
+      input.messageId,
+    )}/copy`;
+    const res = await outlookFetch(ctx.fetch, "copyMessage", url, {
+      method: "POST",
+      body: JSON.stringify({ destinationId: input.destinationId }),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });

package/scripts/createContact.ts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { defineTool, handleIfScriptMain } from "@zapier/connectors-sdk";
+import { z } from "zod";
+
+import { connectionResolvers } from "../connections.ts";
+import { GRAPH_BASE, outlookFetch, parseGraphResponse } from "../lib/graph.ts";
+import { contactSchema, outgoingContactSchema } from "../lib/schemas.ts";
+
+const inputSchema = z.object({ ...outgoingContactSchema.shape }).strict();
+
+const outputSchema = contactSchema;
+
+const definition = defineTool({
+  name: "createContact",
+  title: "Create Contact",
+  description:
+    "Create a personal contact. No single field is required, but set at least a name (givenName/surname/displayName) or an email address so the contact is identifiable. Microsoft allows a maximum of 3 email addresses per contact.",
+  inputSchema,
+  outputSchema,
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  connection: "microsoft-outlook",
+  run: async (input, ctx) => {
+    const url = `${GRAPH_BASE}/me/contacts`;
+    const res = await outlookFetch(ctx.fetch, "createContact", url, {
+      method: "POST",
+      body: JSON.stringify(input),
+    });
+    return parseGraphResponse(res);
+  },
+});
+
+export default definition;
+
+await handleIfScriptMain(import.meta, definition, { connectionResolvers });