outlook-contacts

Outlook Contacts (Microsoft Graph, read & write)

A contacts read-and-write Microsoft Graph skill. Reads and writes the signed-in user's personal contacts through /me/contacts. Does not access mail/files/directory.

All write operations (create, update, delete) default to dry-run; you must pass --apply to execute.

⚠️ Shared auth with outlook-calendar & outlook-todo

This skill reuses the same config and tokens under ~/.outlook-graph/, but it needs the Contacts.ReadWrite scope (in addition to the existing scopes from the calendar/todo skills).

If you already have outlook-calendar set up, you'll need to re-authenticate once to add the Contacts.ReadWrite permission. Run the combined setup:

cd ~/.openclaw/skills/outlook-calendar
./scripts/setup-device-code.sh --client-id  --tenant-id common --force

⚠️ This will ask you to re-consent with an extended scope that includes Contacts.ReadWrite.

For personal Outlook.com accounts, Azure Portal preconfiguration is usually unnecessary — Microsoft supports dynamic consent, and the setup script will request the new scope at login.

Scopes required

The existing setup-device-code.sh in outlook-calendar also includes Calendars.ReadWrite and Tasks.ReadWrite for the calendar/todo skills. They coexist in the same token.

Reading contacts

# List all contacts (paginated, max 200 per page)
./scripts/contacts-read.sh list --format summary

# Search contacts by name, email, or company
./scripts/contacts-read.sh search "jane" --format summary

# Filter by specific field
./scripts/contacts-read.sh list --filter "contains(displayName,'Zhang')" --format json

# Limit results
./scripts/contacts-read.sh list --limit 20 --format summary

# Raw JSON output
./scripts/contacts-read.sh list --format raw

--format options:

• summary (default) — compact table: name, email, phone, company, title
• json — pretty-printed full Graph JSON
• simple — one line per contact: "name 📞phone"
• raw — single-line JSON array

Format examples

summary (default):

NAME                 EMAIL                        PHONE            COMPANY         TITLE
----------------------------------------------------------------------------------------------------

Zhang San            zhang@example.com            13812345678      ABC Corp        Manager
Li Si                li@example.com               13987654321      -               -

Total: 2 contacts

simple — one line per contact with optional phone icon:

Zhang San  📞13812345678
Li Si 

Search syntax

The search subcommand uses Microsoft Graph's $search query parameter on the displayName and emailAddresses fields:

./scripts/contacts-read.sh search "Wang" --format simple
./scripts/contacts-read.sh search "gmail.com" --format summary

Filtering

The --filter option passes an OData $filter expression directly:

./scripts/contacts-read.sh list --filter "jobTitle eq 'Professor'" --format summary
./scripts/contacts-read.sh list --filter "startswith(givenName,'X')" --format json

Writing contacts

⚠️ Safety: every write defaults to dry-run. Pass --apply to execute.

# Get a single contact (read-only, no --apply needed)
./scripts/contacts-write.sh get --contact-id "AAMk..."

# Update a contact (dry-run by default; see payload before applying)
./scripts/contacts-write.sh update --contact-id "AAMk..." \
  --email "new@example.com" --phone "13812345678"

# Actually update (after confirming dry-run output looks correct)
./scripts/contacts-write.sh update --contact-id "AAMk..." \
  --email "new@example.com" --phone "13812345678" --apply

# Create a new contact
./scripts/contacts-write.sh create --display-name "Zhang San" \
  --email "zhang@example.com" --phone "13912345678" --apply

# Delete a contact (always shows the contact first, then asks for YES confirmation)
./scripts/contacts-write.sh delete --contact-id "AAMk..." --apply

Update fields available

• --display-name — full display name
• --given-name — first name
• --surname — last name
• --email — primary email (replaces existing email array)
• --phone — mobile phone number
• --company — company name
• --job-title — job title
• --notes — personal notes

Files in this skill

Troubleshooting

• token scope does not include Contacts.ReadWrite — you need to re-run the outlook-calendar setup script with --force to re-authenticate and get the extended scope.
• Empty results — check that contacts exist in Outlook.com under "People".
• 401 Unauthorized — run scripts/token.sh refresh in the outlook-calendar skill.