Microsoft 365 Graph for OpenClaw Skill

intent

this skill surfaces Microsoft 365 resources (mail, calendar, files, contacts) via the Microsoft Graph API, with optional webhook-based push notifications to openclaw that trigger on incoming mail instead of polling. use this when you need to read/write outlook data, sync calendars, manage onedrive files, or minimize per-message LLM inference cost by reacting to real-time mail events.

inputs

runtime requirements:

• python 3 with requests library installed
• bash and curl (for setup scripts)
• network connectivity to https://graph.microsoft.com and https://login.microsoftonline.com

external connections: microsoft 365 / microsoft graph

1. oauth via device code flow

   • client id (personal default): 952d1b34-682e-48ce-9c54-bac5a96cbd42
   • tenant (personal default): consumers
   • for work/school: use --tenant-id organizations or your tenant GUID with an organization-approved client id
   • default scopes (all): Mail.ReadWrite Mail.Send Calendars.ReadWrite Files.ReadWrite.All Contacts.ReadWrite offline_access
   • tokens stored in state/graph_auth.json (git-ignored)

2. webhook mode (optional, push-based)

   • environment variables (load via systemd from /etc/default/graph-mail-webhook):
     • OPENCLAW_HOOK_URL (required): base URL of openclaw instance
     • OPENCLAW_HOOK_TOKEN (required): bearer token for /hooks/wake endpoint
     • GRAPH_WEBHOOK_CLIENT_STATE (required): opaque validation token for graph webhook payloads
     • OPENCLAW_SESSION_KEY (optional, default hook:graph-mail): session key for dedupe and routing
   • inbound webhook listener expects https or reverse proxy (caddy/nginx)
   • graph subscription lifetime: configurable, default 4200 minutes (70 hours)
   • notification queue stored in state/mail_webhook_queue.jsonl and state/mail_webhook_dedupe.json

3. setup scripts (privileged, ec2/linux only)

   • write to /etc/default/graph-mail-webhook, /etc/caddy/Caddyfile, /etc/systemd/system/
   • restart systemd services and caddy
   • optionally patch openclaw config at user-provided path

4. permission profiles

   • least-privilege scopes documented in docs/permission-profiles.md
   • personal account (consumers): basic mail/calendar/files/contacts
   • work/school: tenant-scoped, may require admin approval for certain scopes

procedure

step 1: oauth authentication (device code flow)

inputs: client id, tenant id (optional)

python scripts/graph_auth.py device-login \
  --client-id 952d1b34-682e-48ce-9c54-bac5a96cbd42 \
  --tenant-id consumers

action: prints a device code and url to https://microsoft.com/devicelogin. open url in browser, enter code, approve scope request with target account.

outputs: access token + refresh token written to state/graph_auth.json. token refresh happens automatically on subsequent calls.

manage auth state:

• python scripts/graph_auth.py status: print current token expiry and refresh status
• python scripts/graph_auth.py refresh: force token refresh
• python scripts/graph_auth.py clear: wipe auth state (requires re-login next time)

note: scope override is disabled; skill always uses DEFAULT_SCOPES. to use different scopes, edit DEFAULT_SCOPES in graph_auth.py before device login. full auth reference: references/auth.md.

---

step 2: fetch and filter mail

inputs: folder name, filter options (unread, top N, include body), message id (optional)

list/filter messages:

python scripts/mail_fetch.py --folder Inbox --top 20 --unread

fetch specific message with body:

python scripts/mail_fetch.py --id <messageId> --include-body --mark-read

move message to folder:

python scripts/mail_fetch.py --id <messageId> --move-to <folderId>

outputs: json array of message objects (id, subject, from, received datetime, unread status, body if requested). folder operations return success/error status. mark-read and move operations return updated message state. full mail reference: references/mail.md.

---

step 3: send email

inputs: recipient email, subject, body (plain text or html file), cc/bcc (optional), attachments (optional), save-to-sent flag (default true)

python scripts/mail_send.py \
  --to user@example.com \
  --subject "Update" \
  --body-file replies/thais.html --html \
  --cc teammate@example.com \
  --attachment docs/proposal.pdf

outputs: message id and sent timestamp. if --no-save-copy is used, message is not stored in Sent Items. default behavior saves copy to Sent Items.

---

step 4: list calendar events in date range

inputs: start datetime (iso8601 utc), end datetime (iso8601 utc), top N (optional)

python scripts/calendar_sync.py list \
  --start 2026-03-03T00:00Z --end 2026-03-05T23:59Z --top 50

outputs: json array of event objects (id, title, start, end, attendees, online meeting url if present, organizer).

---

step 5: create calendar event

inputs: title, start datetime, end datetime, description (optional), online flag (optional, creates teams meeting), location (optional)

python scripts/calendar_sync.py create \
  --title "Team Sync" \
  --start 2026-03-04T14:00Z --end 2026-03-04T15:00Z \
  --description "Weekly standup" \
  --online

outputs: event id, created event object with teams meeting url (if --online used and tenant supports it). note: personal accounts (consumers) may not return join url from graph; create in outlook/teams first and add url to body when needed.

update/cancel event:

python scripts/calendar_sync.py update <event_id> --title "New Title"
python scripts/calendar_sync.py cancel <event_id>

full calendar reference: references/calendar.md.

---

step 6: onedrive file operations

inputs: local path, remote path, operation (list/upload/download/move/share)

list folders and files:

python scripts/drive_ops.py list --path /

upload file:

python scripts/drive_ops.py upload --local notes/briefing.docx --remote /Clients/briefing.docx

download file:

python scripts/drive_ops.py download --remote /Clients/briefing.docx --local /tmp/briefing.docx

move/rename:

python scripts/drive_ops.py move --remote /old-name.docx --new-path /new-name.docx

share link:

python scripts/drive_ops.py share --remote /file.docx

outputs: file metadata (id, name, size, modified date), sharing link. script resolves localized folder aliases (e.g., Documents and Documentos). full drive reference: references/drive.md.

---

step 7: contacts crud

inputs: given name, surname, email, phone (optional)

list contacts:

python scripts/contacts_ops.py list --top 20

search contacts:

python scripts/contacts_ops.py list --search "john"

create contact:

python scripts/contacts_ops.py create --given-name Jane --surname Doe --email jane.doe@example.com

update contact:

python scripts/contacts_ops.py update <contactId> --email newemail@example.com

delete contact:

python scripts/contacts_ops.py delete <contactId>

outputs: contact id, full contact object with all fields. full contacts reference: references/contacts.md.

---

step 8: webhook adapter setup (push-based mail)

this step is optional. use only if you want to reduce polling and react to incoming mail in real-time.

step 8a: start webhook listener (no privilege required)

inputs: host, port, path, client-state token

python scripts/mail_webhook_adapter.py serve \
  --host 0.0.0.0 --port 8789 --path /graph/mail \
  --client-state "$GRAPH_WEBHOOK_CLIENT_STATE"

action: binds to host:port, listens for graph webhook payloads at /path, validates clientState, enqueues messages to state/mail_webhook_queue.jsonl.

outputs: running http server. logs all inbound notifications and validation results.

---

step 8b: create graph subscription

inputs: notification url (https), client-state token, subscription lifetime in minutes

python scripts/mail_subscriptions.py create \
  --notification-url "https://graph-hook.example.com/graph/mail" \
  --client-state "$GRAPH_WEBHOOK_CLIENT_STATE" \
  --minutes 4200

action: registers subscription with graph api for resource me/messages (default; covers all mail folders). graph will deliver notifications to the url.

outputs: subscription id, expiry time, resource being monitored.

manage subscriptions:

python scripts/mail_subscriptions.py status --subscription-id <id>
python scripts/mail_subscriptions.py renew --subscription-id <id> --minutes 4200
python scripts/mail_subscriptions.py delete --subscription-id <id>
python scripts/mail_subscriptions.py list

---

step 8c: start async worker (polls queue, sends wake signals)

inputs: session key, openclaw hook url, openclaw hook token

python scripts/mail_webhook_worker.py loop \
  --session-key "$OPENCLAW_SESSION_KEY" \
  --hook-url "$OPENCLAW_HOOK_URL" \
  --hook-token "$OPENCLAW_HOOK_TOKEN"

action: polls state/mail_webhook_queue.jsonl for new entries. deduplicates via state/mail_webhook_dedupe.json. sends wake signal to $HOOK_URL/hooks/wake (mode=now) for each unique message. worker runs continuously.

outputs: wake signals posted to openclaw. dedupe state maintains message ids to prevent duplicate signals. logs all sends.

---

step 8d: automated setup (ec2 + systemd + caddy)

privileged operation. review carefully before running.

inputs: domain, hook url, hook token, session key, client-state, repo root

sudo bash scripts/setup_mail_webhook_ec2.sh \
  --domain graphhook.example.com \
  --hook-url http://127.0.0.1:18789/hooks/wake \
  --hook-token "<OPENCLAW_HOOK_TOKEN>" \
  --session-key "hook:graph-mail" \
  --client-state "<GRAPH_WEBHOOK_CLIENT_STATE>" \
  --repo-root "$(pwd)"

action (with --dry-run first): writes /etc/default/graph-mail-webhook, sets up caddy reverse proxy with tls, creates systemd services for adapter and worker, enables auto-renewal of graph subscription via systemd timer.

outputs: systemd services running. tls certificate provisioned. environment config in place. full webhook setup reference: references/mail_webhook_adapter.md.

---

step 8e: one-command e2e setup

privileged operation. use --dry-run first.

sudo bash scripts/run_mail_webhook_e2e_setup.sh \
  --domain graphhook.example.com \
  --hook-token "<OPENCLAW_HOOK_TOKEN>" \
  --hook-url "http://127.0.0.1:18789/hooks/wake" \
  --session-key "hook:graph-mail" \
  --test-email "tar.alitar@outlook.com"

action: combines all setup steps (oauth, adapter, subscription, worker, systemd, caddy). sends test email to verify end-to-end delivery.

outputs: printed config summary, READY_FOR_PUSH: YES on success, READY_FOR_PUSH: NO with error details on failure.

optional: integrate with openclaw config:

sudo bash scripts/run_mail_webhook_e2e_setup.sh \
  --domain graphhook.example.com \
  --hook-token "<OPENCLAW_HOOK_TOKEN>" \
  --configure-openclaw-hooks \
  --openclaw-config "/home/ubuntu/.openclaw/openclaw.json" \
  --openclaw-service-name "auto" \
  --openclaw-hooks-path "/hooks" \
  --openclaw-allow-request-session-key true \
  --test-email "tar.alitar@outlook.com"

action: additionally patches openclaw.json to register the /hooks/wake endpoint and restarts openclaw service.

---

step 8f: smoke tests

privileged operation.

sudo bash scripts/run_mail_webhook_smoke_tests.sh \
  --domain graphhook.example.com \
  --create-subscription \
  --test-email tar.alitar@outlook.com

action: validates adapter is listening, graph can reach callback url, subscription was created, test email can be sent and received by adapter, dedupe and queue logic work.

outputs: READINESS VERDICT: READY_FOR_PUSH if all checks pass, READINESS VERDICT: NOT_READY with failure reasons otherwise.

---

step 9: logging and audit

each core script appends one json line to state/graph_ops.log with timestamp, action, key parameters, and result status. never commit tokens or logs. run all commands from repo root; adjust paths if running elsewhere.

---

decision points

if using personal account (microsoft.com):

• use default tenant id consumers and public client id
• teams meeting provisioning via graph may not return a join url; create in outlook/teams first and add url to event body

if using work/school account:

• use --tenant-id organizations or explicit tenant guid
• use organization-approved client id, not public default
• certain scopes may require admin consent (check tenant admin approval flow)

if auth token is invalid (401/invalid_grant):

• try python scripts/graph_auth.py refresh
• if refresh fails, run python scripts/graph_auth.py clear and repeat device login from step 1

if permission denied (403/AccessDenied):

• missing required scope or policy/licensing issue on tenant
• re-run device login and approve all scopes, or contact tenant admin

if rate limited (429/Throttled):

• scripts include basic exponential backoff
• wait a few seconds and retry manually, or let script handle retry

if ssl/tls error (requests.exceptions.SSLError):

• verify system date/time are correct
• verify ca certificate bundle is current
• check corporate proxy/firewall not blocking microsoft endpoints

if webhook adapter is running but openclaw not receiving signals:

• verify $OPENCLAW_HOOK_TOKEN matches openclaw bearer token
• verify $OPENCLAW_HOOK_URL is reachable from adapter host
• check adapter logs for queue entries and send errors
• verify GRAPH_WEBHOOK_CLIENT_STATE matches graph subscription payload

if graph subscription is not delivering notifications:

• verify subscription exists: mail_subscriptions.py list
• verify adapter is listening and reachable from internet
• check graph admin portal for subscription health/errors
• renew subscription: mail_subscriptions.py renew --subscription-id <id>

if duplicate wake signals are sent to openclaw:

• dedupe json (state/mail_webhook_dedupe.json) is corrupted or not persisting
• restart worker and clear dedupe file if safe
• check disk space and file permissions on state/ directory

before running privileged setup scripts:

• always run with --dry-run first to review all actions
• review target file writes (/etc/default/, /etc/systemd/, /etc/caddy/)
• test on non-production host before production rollout

output contract

mail fetch outputs: json array of message objects with keys: id, subject, from, receivedDateTime, isRead, bodyPreview, body (if --include-body).

mail send outputs: json object with keys: id, sentDateTime.

calendar list outputs: json array of event objects with keys: id, subject, start, end, attendees, isOnlineMeeting, onlineMeetingUrl (if online), organizer.

calendar create outputs: json object with full event details including id, onlineMeetingUrl (if applicable).

drive list outputs: json array of file/folder objects with keys: id, name, size, lastModifiedDateTime, folder (boolean), webUrl.

drive upload/download outputs: json object with file metadata and operation status.

contacts list/create/update outputs: json object or array with keys: id, displayName, givenName, surname, emailAddresses, mobilePhone.

webhook adapter: http server listening on specified host:port. logs json lines to stdout with request received, validation status, queue written status.

webhook worker: continuously running, appends dedupe state to json file, posts http post requests to openclaw hook url.

auth state: state/graph_auth.json contains access_token, refresh_token, expires_at. managed by utils.get_access_token().

operation log: state/graph_ops.log contains one json line per operation (mail, calendar, drive, contacts, auth, subscription, adapter, worker).

webhook queue: state/mail_webhook_queue.jsonl contains one json line per incoming notification (message id, timestamp, graph payload).

webhook dedupe: state/mail_webhook_dedupe.json contains set of processed message ids to prevent duplicate signals.

privileged setup outputs: /etc/default/graph-mail-webhook (env vars), /etc/systemd/system/graph-mail-webhook-adapter.service, /etc/systemd/system/graph-mail-webhook-worker.service, /etc/systemd/system/graph-mail-subscriptions.timer, /etc/caddy/Caddyfile (reverse proxy config). services are enabled and running.

outcome signal

auth success: graph_auth.py status prints "Valid" and expiry time in the future. subsequent scripts run without 401 errors.

mail operations success: fetch returns message list; send returns sent message id; move returns success status.

calendar operations success: list returns events in date range; create returns event id with meeting url (if online); update/cancel return updated event state.

drive operations success: list returns folders/files; upload/download complete without io errors; share returns public link.

contacts operations success: list returns contact array; create/update return contact id; delete returns no error.

webhook adapter success: server binds to host:port, logs "listening on port X", receives graph payloads, validates clientState, writes to queue.jsonl.

webhook worker success: worker loops continuously, deduplicates entries, posts wake signals to openclaw hook url, logs "signal sent" for each unique message.

smoke tests success: test prints READINESS VERDICT: READY_FOR_PUSH and all sub-checks pass (listener ok, connectivity ok, subscription created, test email delivered, queue populated).

e2e setup success: setup script prints READY_FOR_PUSH: YES, all systemd services are active/running, tls certificate is valid, graph subscription is registered.

---

credits: original skill authored and maintained at https://github.com/draeden79/microsoft-365-graph-openclaw. enriched for implexa standards to clarify inputs, decision points, and output contracts.