VX Agents

OpenAPI Marketplace · Email

Outlook Mail (Microsoft Graph)

v1.0.0 · 15 endpoints · 0 connections · shared by vx.ai

Lets an agent work the signed-in user's Microsoft 365 / Outlook mailbox through Microsoft Graph v1.0: search and read messages and folders, draft or send replies and forwards, send new mail, flag, categorize, mark read and move messages. Based on the Microsoft Graph API specification.

Connect this API to an AI agent Browse all specs

What you can do with Outlook Mail (Microsoft Graph) via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

MethodPathOperationDescription
GET /me getMe Get the signed-in user's name and email address
GET /me/mailFolders listMailFolders List mail folders (Inbox, Sent Items, custom folders) with ids
GET /me/mailFolders/{mailFolder-id}/messages listFolderMessages List or search messages in one folder (e.g. inbox)
GET /me/messages listMessages Search or filter messages across the whole mailbox
GET /me/messages/{message-id} getMessage Read one message (sender, recipients, body)
PATCH /me/messages/{message-id} updateMessage Mark read/unread, flag, set categories, or edit a draft
POST /me/messages/{message-id}/microsoft.graph.move moveMessage Move a message to another folder (e.g. archive)
POST /me/messages/{message-id}/microsoft.graph.createReply createReplyDraft Create a reply draft for a message (not sent)
POST /me/messages/{message-id}/microsoft.graph.createReplyAll createReplyAllDraft Create a reply-all draft for a message (not sent)
POST /me/messages/{message-id}/microsoft.graph.createForward createForwardDraft Create a forward draft for a message (not sent)
POST /me/messages/{message-id}/microsoft.graph.send sendDraft Send an existing draft message
POST /me/messages/{message-id}/microsoft.graph.reply replyToMessage Reply to the sender immediately
POST /me/messages/{message-id}/microsoft.graph.replyAll replyAllToMessage Reply to all recipients immediately
POST /me/messages/{message-id}/microsoft.graph.forward forwardMessage Forward a message to new recipients immediately
POST /me/microsoft.graph.sendMail sendMail Send a new email immediately

Authentication

microsoftOAuth

OAuth 2.0

Scopes: User.Read Mail.Read Mail.ReadWrite Mail.Send offline_access

Microsoft identity platform OAuth 2.0 (authorization code, delegated permissions for the signed-in user).

How to get a credential

  1. In the Microsoft Entra admin center go to App registrations > New registration; choose the supported account types (single tenant for your organization, or multitenant + personal accounts).
  2. Under Authentication, add a Web platform with the VX Agents redirect URI shown in the credential form.
  3. Under Certificates & secrets, create a client secret and copy its value.
  4. Under API permissions, add Microsoft Graph delegated permissions Mail.Read, Mail.ReadWrite, Mail.Send, User.Read and offline_access. Grant admin consent if your tenant requires it.
  5. Paste the application (client) ID and secret into the VX Agents credential and sign in with the mailbox owner's account.

Permissions used

Scope Operations
User.Read getMe
Mail.Read listMailFolders, listFolderMessages, listMessages, getMessage
Mail.ReadWrite updateMessage, moveMessage, createReplyDraft, createReplyAllDraft, createForwardDraft
Mail.Send sendMail, sendDraft, replyToMessage, replyAllToMessage, forwardMessage
offline_access refresh tokens so the connection stays signed in

Common errors

  • 401 Unauthorized (InvalidAuthenticationToken): the token expired or is for the wrong resource. Reconnect the credential; make sure offline_access is granted.
  • 403 Forbidden (ErrorAccessDenied): a permission is missing or admin consent was not granted. Add it in API permissions and reconnect.
  • 400 Bad Request: invalid $filter/$search syntax (they cannot be combined with $orderby on most fields) or a malformed recipient.
  • 429 Too Many Requests: mailbox throttling. Wait for the Retry-After seconds and retry.

Store the connection as a VX Agents OAuth credential. Never paste tokens into chat.

Usage guide

Setup

  • Connect a Microsoft OAuth credential (delegated) with Mail.Read, Mail.ReadWrite, Mail.Send, User.Read and offline_access. The agent works in the signed-in user's own mailbox only.
  • Call getMe once to learn the user's address. Well-known folder ids work anywhere a folder id is asked: inbox, sentitems, drafts, archive, deleteditems, junkemail.

Triage and reply to email

  1. Find mail: listFolderMessages with mailFolder-id=inbox, $filter=isRead eq false, $orderby=receivedDateTime desc, $top=25, $select=id,subject,from,receivedDateTime,bodyPreview,conversationId. For free text use listMessages with $search="invoice 1042" (no $orderby with $search).
  2. getMessage to read the full body; to read a whole thread, listMessages with $filter=conversationId eq '<id>'.
  3. Write the answer with createReplyDraft / createReplyAllDraft (put the text in comment), or createForwardDraft with toRecipients. Adjust the draft with updateMessage if needed. Show the draft to the user.
  4. After the user confirms, sendDraft with the draft id. replyToMessage, replyAllToMessage, forwardMessage and sendMail send immediately: use them only when the user has approved the exact text and recipients.
  5. Tidy up: updateMessage with isRead: true, flag: {flagStatus: "flagged"} or categories; moveMessage with destinationId: "archive".

Good to know

  • Sending mail cannot be undone: always confirm recipients, subject and body first.
  • Paging: follow @odata.nextLink (it already contains $skip/$skiptoken). $top max is 1000; keep it small and use $select to save tokens.
  • Times are ISO 8601 UTC, e.g. receivedDateTime ge 2026-10-01T00:00:00Z.
  • moveMessage returns the message with a new id; use that id afterwards.
  • body.contentType is html by default; send text for plain replies.
  • No delete operations by design: archive instead.

How to use this spec

  1. Create a free VX Agents account (sandbox tools included).
  2. Open the marketplace and connect “Outlook Mail (Microsoft Graph)” to an agent.
  3. Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.

Related APIs

  • Postmark Transactional Email — Send transactional email through a Postmark server (plain or from a template), search sent messages and read their deli…
  • SendGrid Email — Send transactional email (plain or from a dynamic template), look up templates, check bounces and unsubscribes before s…
  • Gmail Inbox & Send — Lets an agent work a Gmail inbox: search and read messages and threads, draft replies, send email, and label, archive o…