{"skill":{"slug":"outlook-api","displayName":"Outlook","summary":"Microsoft Outlook API integration with managed OAuth. Read, send, and manage emails, folders, calendar events, and contacts via Microsoft Graph. Use this ski...","description":"---\nname: outlook\ndescription: |\n  Microsoft Outlook API integration with managed OAuth. Read, send, and manage emails, folders, calendar events, and contacts via Microsoft Graph. Use this skill when users want to interact with Outlook. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\ncompatibility: Requires network access and valid Maton API key\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# Outlook\n\nAccess the Microsoft Outlook API (via Microsoft Graph) with managed OAuth authentication. Read, send, and manage emails, folders, calendar events, and contacts.\n\n## Quick Start\n\n**CLI:**\n\n```bash\nmaton outlook message list --folder Inbox --top 25\n```\n\n```bash\nmaton api '/outlook/v1.0/me/messages?$top=25'\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/outlook/v1.0/me')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://api.maton.ai/outlook/{native-api-path}\n```\n\nMaton proxies requests to `graph.microsoft.com` and automatically injects your OAuth token.\n\n## Installation\n\n**NPM:**\n```bash\nnpm install -g @maton-ai/cli\n```\n\n**Homebrew:**\n```bash\nbrew install maton-ai/cli/maton\n```\n\n## Authentication\n\n**CLI:**\n\n```bash\nmaton login                          # Opens browser for API key\nmaton login --interactive            # Skip browser, paste API key directly\nmaton whoami                         # Show current auth state\n```\n\n**Manual:**\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n4. Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n## Connection Management\n\nManage your Microsoft OAuth connections at `https://api.maton.ai`.\n\n### List Connections\n\n**CLI:**\n\n```bash\nmaton connection list outlook --status ACTIVE\n```\n\n```bash\nmaton api -X GET /connections -f app=outlook -f status=ACTIVE\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections?app=outlook&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n**CLI:**\n\n```bash\nmaton connection create outlook\n```\n\n```bash\nmaton api /connections -f app=outlook\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'outlook'}).encode()\nreq = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n**CLI:**\n\n```bash\nmaton connection view {connection_id}\n```\n\n```bash\nmaton api /connections/{connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"{connection_id}\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2025-12-08T07:20:53.488460Z\",\n    \"last_updated_time\": \"2026-01-31T20:03:32.593153Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"outlook\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n**CLI:**\n\n```bash\nmaton connection delete {connection_id}\n```\n\n```bash\nmaton api -X DELETE /connections/{connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple Outlook connections, specify which one to use:\n\n**CLI:**\n\n```bash\nmaton outlook message list --folder Inbox --connection {connection_id}\n```\n\n```bash\nmaton api /outlook/v1.0/me/messages --connection {connection_id}\n```\n\n**Python:**\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/outlook/v1.0/me')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '{connection_id}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf you have multiple connections, always specify the connection to ensure requests go to the intended account.\n\n## Security & Permissions\n\n- Access is scoped to messages, mail folders, calendar events, and contacts within the connected Outlook account.\n- **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.\n\n## API Reference\n\n### User Profile\n\n```bash\nGET /outlook/v1.0/me\n```\n\nExample:\n\n```bash\nmaton outlook whoami\n```\n\n### Mail Folders\n\n#### List Mail Folders\n\n```bash\nGET /outlook/v1.0/me/mailFolders\n```\n\nExample:\n\n```bash\nmaton outlook folder list\n```\n\n#### Get Mail Folder\n\n```bash\nGET /outlook/v1.0/me/mailFolders/{folderId}\n```\n\nWell-known folder names: `Inbox`, `Drafts`, `SentItems`, `DeletedItems`, `Archive`, `JunkEmail`\n\nExample:\n\n```bash\nmaton outlook folder view {folderId}\n```\n\n#### Create Mail Folder\n\n```bash\nPOST /outlook/v1.0/me/mailFolders\nContent-Type: application/json\n\n{\n  \"displayName\": \"My Folder\"\n}\n```\n\nExample:\n\n```bash\nmaton outlook folder create --name \"My Folder\"\n```\n\n#### Delete Mail Folder\n\n```bash\nDELETE /outlook/v1.0/me/mailFolders/{folderId}\n```\n\nExample:\n\n```bash\nmaton outlook folder delete {folderId}\n```\n\n#### List Child Folders\n\n```bash\nGET /outlook/v1.0/me/mailFolders/{folderId}/childFolders\n```\n\nExample:\n\n```bash\nmaton outlook folder list --parent {folderId}\n```\n\n### Messages\n\n#### List Messages\n\n```bash\nGET /outlook/v1.0/me/messages\n```\n\nExample:\n\n```bash\nmaton outlook message list\n```\n\nFrom specific folder:\n\n```bash\nGET /outlook/v1.0/me/mailFolders/Inbox/messages\n```\n\nExample:\n\n```bash\nmaton outlook message list --folder Inbox\n```\n\nWith query filter:\n\n```bash\nGET /outlook/v1.0/me/messages?$filter=isRead eq false&$top=10\n```\n\nExample:\n\n```bash\nmaton outlook message list --filter \"isRead eq false\" --top 10\n```\n\n#### Get Message\n\n```bash\nGET /outlook/v1.0/me/messages/{messageId}\n```\n\nExample:\n\n```bash\nmaton outlook message view {messageId}\n```\n\n#### Create Draft\n\n```bash\nPOST /outlook/v1.0/me/messages\nContent-Type: application/json\n\n{\n  \"subject\": \"Hello\",\n  \"body\": {\n    \"contentType\": \"Text\",\n    \"content\": \"This is the email body.\"\n  },\n  \"toRecipients\": [\n    {\n      \"emailAddress\": {\n        \"address\": \"recipient@example.com\"\n      }\n    }\n  ]\n}\n```\n\nExample:\n\n```bash\nmaton outlook message draft --to recipient@example.com --subject \"Hello\" --body \"This is the email body.\"\n```\n\n#### Send Message\n\n```bash\nPOST /outlook/v1.0/me/sendMail\nContent-Type: application/json\n\n{\n  \"message\": {\n    \"subject\": \"Hello\",\n    \"body\": {\n      \"contentType\": \"Text\",\n      \"content\": \"This is the email body.\"\n    },\n    \"toRecipients\": [\n      {\n        \"emailAddress\": {\n          \"address\": \"recipient@example.com\"\n        }\n      }\n    ]\n  },\n  \"saveToSentItems\": true\n}\n```\n\nExample:\n\n```bash\nmaton outlook message send --to recipient@example.com --subject \"Hello\" --body \"This is the email body.\"\n```\n\n#### Send Existing Draft\n\n```bash\nPOST /outlook/v1.0/me/messages/{messageId}/send\n```\n\nExample:\n\n```bash\nmaton outlook message send {messageId}\n```\n\n#### Update Message\n\n```bash\nPATCH /outlook/v1.0/me/messages/{messageId}\nContent-Type: application/json\n\n{\n  \"isRead\": true\n}\n```\n\nExample:\n\n```bash\nmaton outlook message update {messageId} --read\n```\n\n#### Delete Message\n\n```bash\nDELETE /outlook/v1.0/me/messages/{messageId}\n```\n\nExample:\n\n```bash\nmaton outlook message delete {messageId}\n```\n\n#### Move Message\n\n```bash\nPOST /outlook/v1.0/me/messages/{messageId}/move\nContent-Type: application/json\n\n{\n  \"destinationId\": \"{folderId}\"\n}\n```\n\nExample:\n\n```bash\nmaton outlook message move {messageId} --to {folderId}\n```\n\n#### Search Messages\n\nExample:\n\n```bash\nmaton outlook message search \"quarterly report\"\n```\n\n### Calendar\n\n#### List Calendars\n\n```bash\nGET /outlook/v1.0/me/calendars\n```\n\nExample:\n\n```bash\nmaton outlook calendar list\n```\n\n#### List Events\n\n```bash\nGET /outlook/v1.0/me/calendar/events\n```\n\nExample:\n\n```bash\nmaton outlook event list\n```\n\nWith date filter:\n\n```bash\nGET /outlook/v1.0/me/calendar/events?$filter=start/dateTime ge '2024-01-01'&$top=10\n```\n\nExample:\n\n```bash\nmaton outlook event list --filter \"start/dateTime ge '2024-01-01'\" --top 10\n```\n\n#### Get Event\n\n```bash\nGET /outlook/v1.0/me/events/{eventId}\n```\n\nExample:\n\n```bash\nmaton outlook event view {eventId}\n```\n\n#### Create Event\n\n```bash\nPOST /outlook/v1.0/me/calendar/events\nContent-Type: application/json\n\n{\n  \"subject\": \"Meeting\",\n  \"start\": {\n    \"dateTime\": \"2024-01-15T10:00:00\",\n    \"timeZone\": \"UTC\"\n  },\n  \"end\": {\n    \"dateTime\": \"2024-01-15T11:00:00\",\n    \"timeZone\": \"UTC\"\n  },\n  \"attendees\": [\n    {\n      \"emailAddress\": {\n        \"address\": \"attendee@example.com\"\n      },\n      \"type\": \"required\"\n    }\n  ]\n}\n```\n\nExample:\n\n```bash\nmaton outlook event create --subject \"Meeting\" --start 2024-01-15T10:00:00 --end 2024-01-15T11:00:00 --timezone UTC --attendees attendee@example.com\n```\n\n#### Delete Event\n\n```bash\nDELETE /outlook/v1.0/me/events/{eventId}\n```\n\nExample:\n\n```bash\nmaton outlook event delete {eventId}\n```\n\n### Contacts\n\n#### List Contacts\n\n```bash\nGET /outlook/v1.0/me/contacts\n```\n\nExample:\n\n```bash\nmaton outlook contact list\n```\n\n#### Get Contact\n\n```bash\nGET /outlook/v1.0/me/contacts/{contactId}\n```\n\nExample:\n\n```bash\nmaton outlook contact view {contactId}\n```\n\n#### Create Contact\n\n```bash\nPOST /outlook/v1.0/me/contacts\nContent-Type: application/json\n\n{\n  \"givenName\": \"John\",\n  \"surname\": \"Doe\",\n  \"emailAddresses\": [\n    {\n      \"address\": \"john.doe@example.com\"\n    }\n  ]\n}\n```\n\nExample:\n\n```bash\nmaton outlook contact create --given-name John --surname Doe --email john.doe@example.com\n```\n\n#### Delete Contact\n\n```bash\nDELETE /outlook/v1.0/me/contacts/{contactId}\n```\n\nExample:\n\n```bash\nmaton outlook contact delete {contactId}\n```\n\n## Query Parameters\n\nUse OData query parameters:\n\n- `$top=10` - Limit results\n- `$skip=20` - Skip results (pagination)\n- `$select=subject,from` - Select specific fields\n- `$filter=isRead eq false` - Filter results\n- `$orderby=receivedDateTime desc` - Sort results\n- `$search=\"keyword\"` - Search content\n\n## Pagination\n\nOutlook uses cursor-based pagination. The CLI automatically paginates with '--paginate'.\n\nExample:\n\n```bash\nmaton outlook message list --folder Inbox --paginate\n```\n\n## Code Examples\n\n### CLI\n\n```bash\n# List recent inbox messages\nmaton outlook message list --folder Inbox --top 25\n\n# Send an email\nmaton outlook message send --to alice@example.com --subject hi --body \"hello\"\n\n# Search for messages\nmaton outlook message search \"quarterly report\"\n```\n\n### JavaScript\n\n```javascript\nconst response = await fetch(\n  'https://api.maton.ai/outlook/v1.0/me/messages?$top=10',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`\n    }\n  }\n);\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\nresponse = requests.get(\n    'https://api.maton.ai/outlook/v1.0/me/messages',\n    headers={'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'},\n    params={'$top': 10, '$filter': 'isRead eq false'}\n)\n```\n\n## Notes\n\n- Use `me` as the user identifier for the authenticated user\n- Message body content types: `Text` or `HTML`\n- Well-known folder names work as folder IDs: `Inbox`, `Drafts`, `SentItems`, etc.\n- Calendar events use ISO 8601 datetime format\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get \"Invalid API key\" errors when piping.\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Missing Outlook connection |\n| 401 | Invalid or missing Maton API key |\n| 429 | Rate limited (10 req/sec per account) |\n| 4xx/5xx | Passthrough error from Microsoft Graph API |\n\n### Troubleshooting: API Key Issues\n\n**CLI:**\n\n1. Check your auth state:\n\n```bash\nmaton whoami\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\nmaton connection list\n```\n\n**Manual:**\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `outlook`. For example:\n\n- Correct: `https://api.maton.ai/outlook/v1.0/me/messages`\n- Incorrect: `https://api.maton.ai/v1.0/me/messages`\n\n## Resources\n\n- [Microsoft Graph API Overview](https://learn.microsoft.com/en-us/graph/api/overview)\n- [Mail API](https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview)\n- [Calendar API](https://learn.microsoft.com/en-us/graph/api/resources/calendar)\n- [Contacts API](https://learn.microsoft.com/en-us/graph/api/resources/contact)\n- [Query Parameters](https://learn.microsoft.com/en-us/graph/query-parameters)\n- [Maton CLI Manual](https://cli.maton.ai/manual)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","topics":["Api Integration","Calendar"],"tags":{"latest":"1.0.5"},"stats":{"comments":3,"downloads":23036,"installsAllTime":770,"installsCurrent":69,"stars":45,"versions":6},"createdAt":1770117136202,"updatedAt":1781739759130},"latestVersion":{"version":"1.0.5","createdAt":1778148469709,"changelog":"**Adds CLI usage examples and installation instructions for improved integration:**\n\n- Expanded documentation to include Maton CLI commands for all major Outlook operations (messages, folders, calendar, contacts, connections).\n- Added installation instructions for CLI via npm and Homebrew.\n- Included CLI login and authentication steps alongside manual/environment variable method.\n- Provided CLI, Python, and API examples for each operation where applicable.\n- Improved guidance on managing multiple Outlook connections with CLI options.\n- No API or functional changes; documentation improvements only.","license":"MIT-0"},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"byungkyu","userId":"s174c3s2kc1ehqj1ytzntezj2983e2aj","displayName":"byungkyu","image":"https://avatars.githubusercontent.com/u/16563684?v=4"},"moderation":null}