Implementation:Microsoft Semantic kernel MessagesPlugin OpenAPI

Knowledge Sources	Microsoft_Semantic_kernel
Domains	OpenAPI, Copilot_Agent_Plugins
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete OpenAPI 3.0.1 specification for the Microsoft Graph Messages API, used as the MessagesPlugin definition within the Copilot Agent Plugins sample of Semantic Kernel.

Description

This file is an OpenAPI 3.0.1 YAML specification describing a subset of the Microsoft Graph v1.0 OData service focused on email message operations. It defines two endpoints:

GET /me/messages -- Lists messages in the signed-in user's mailbox (including Deleted Items and Clutter folders) with full OData query parameter support ($top, $skip, $search, $filter, $count, $orderby, $select, $expand) and an includeHiddenMessages parameter. Supports pagination via @odata.nextLink with a default page size of 10 messages.
POST /me/sendMail -- Sends a message specified in the request body using JSON or MIME format, with an option to save to the Sent Items folder.

The specification includes comprehensive schema definitions for Microsoft Graph messaging entities:

microsoft.graph.message -- Full message model with properties for subject, body, bodyPreview, sender, from, toRecipients, ccRecipients, bccRecipients, replyTo, importance, inferenceClassification, flag, conversationId, internetMessageHeaders, attachments, and more.
microsoft.graph.recipient -- Recipient with emailAddress reference.
microsoft.graph.itemBody -- Message body with content and contentType (text/html).
microsoft.graph.followupFlag -- Follow-up flag with status, start, due, and completed date-times.
microsoft.graph.attachment -- Attachment with contentType, name, size, isInline.

This file is identical in content to the AstronomyPlugin's messages-openapi.yml but is placed in the MessagesPlugin directory for its own plugin context.

Usage

This file is used by the Copilot Agent Plugins Concepts sample to demonstrate how email messaging operations can be exposed as agent-callable tools. Developers use this to understand how to build Copilot Agent Plugins for email scenarios with Microsoft Graph.

Code Reference

Source Location

Repository: Microsoft_Semantic_kernel
File: dotnet/samples/Concepts/Resources/Plugins/CopilotAgentPlugins/MessagesPlugin/messages-openapi.yml
Lines: 1-513

Signature

openapi: 3.0.1
info:
  title: OData Service for namespace microsoft.graph - Subset
  description: This OData service is located at https://graph.microsoft.com/v1.0
  version: v1.0
servers:
  - url: https://graph.microsoft.com/v1.0
paths:
  /me/messages:
    get:
      tags:
        - me.message
      summary: Get the messages in the signed-in user's mailbox
      operationId: me_ListMessages
      parameters:
        - name: includeHiddenMessages
          in: query
          description: Include Hidden Messages
          schema:
            type: string
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'

Import

// Loaded as part of the Copilot Agent Plugin configuration:
await kernel.ImportPluginFromOpenApiAsync(
    "MessagesPlugin",
    Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
                 "MessagesPlugin", "messages-openapi.yml"));

I/O Contract

Inputs

Name	Type	Required	Description
includeHiddenMessages	string (query)	no	Include hidden messages in the response.
$top	integer (query)	no	Show only the first n items (range: 1-1000, default: 10).
$skip	integer (query)	no	Skip the first n items.
$search	string (query)	no	Search items by search phrases.
$filter	string (query)	no	Filter items by property values.
$count	boolean (query)	no	Include count of items.
$orderby	array of strings (query)	no	Order items by property values.
$select	array of strings (query)	no	Select properties to be returned.
$expand	array of strings (query)	no	Expand related entities.
Message	microsoft.graph.message (body)	yes	Message object for the sendMail operation.
SaveToSentItems	boolean (body)	no	Whether to save the message to Sent Items. Default: false.

Outputs

Name	Type	Description
messageCollectionResponse	object	Paginated collection of message objects with @odata.count, @odata.nextLink, and value array containing microsoft.graph.message entities.
204 No Content	(empty)	Success response for the sendMail operation.

Usage Examples

Loading the MessagesPlugin

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey)
    .Build();

await kernel.ImportPluginFromOpenApiAsync(
    "MessagesPlugin",
    Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
                 "MessagesPlugin", "messages-openapi.yml"));

// List recent messages
var messages = await kernel.InvokeAsync("MessagesPlugin", "me_ListMessages",
    new KernelArguments { ["$top"] = "5", ["$select"] = "subject,from,receivedDateTime" });

// Send a mail
var sendResult = await kernel.InvokeAsync("MessagesPlugin", "me_sendMail",
    new KernelArguments { ["body"] = sendMailPayload });

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment