Microsoft Office 365 Mail API

openapi: 3.2.0
info:
  title: Microsoft Office 365 Microsoft Graph Calendar Mail API
  description: The Microsoft Graph API provides a unified programmability model to access data, intelligence, and insights from Microsoft 365, Windows, and Enterprise Mobility + Security. It serves as the gateway to data and intelligence in Microsoft 365, enabling applications to interact with users, groups, mail, calendars, files, and other organizational resources through a single REST endpoint.
  version: 1.0.0
  termsOfService: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  license:
    name: Microsoft API License
    url: https://docs.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-documentation:
    url: https://learn.microsoft.com/en-us/graph/overview
  x-api-explorer:
    url: https://developer.microsoft.com/en-us/graph/graph-explorer
servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint
- url: https://graph.microsoft.com/beta
  description: Microsoft Graph beta endpoint (preview features)
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Mail
  description: Access and manage Outlook mail messages, mail folders, and message attachments. Supports reading, creating, sending, replying, forwarding, and organizing email.
  externalDocs:
    url: https://learn.microsoft.com/en-us/graph/api/resources/mail-api-overview?view=graph-rest-1.0
paths:
  /me/messages:
    get:
      operationId: listMessages
      summary: Microsoft Office 365 List Messages
      description: Get the messages in the signed-in user's mailbox (including Deleted Items and Clutter folders). Depending on the page size and mailbox data, getting messages may incur multiple requests. The default page size is 10. Requires Mail.ReadBasic, Mail.Read, or Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A collection of message objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCollectionResponse'
              examples:
                Listmessages200Example:
                  summary: Default listMessages 200 response
                  x-microcks-default: true
                  value:
                    '@odata.context': example_value
                    '@odata.count': 10
                    '@odata.nextLink': https://www.example.com
                    value:
                    - id: abc123
                      subject: example_value
                      bodyPreview: example_value
                      toRecipients: {}
                      ccRecipients: {}
                      bccRecipients: {}
                      replyTo: {}
                      conversationId: '500123'
                      conversationIndex: example_value
                      receivedDateTime: '2026-01-15T10:30:00Z'
                      sentDateTime: '2026-01-15T10:30:00Z'
                      createdDateTime: '2026-01-15T10:30:00Z'
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      hasAttachments: true
                      internetMessageId: '500123'
                      importance: low
                      isRead: true
                      isDraft: true
                      isDeliveryReceiptRequested: true
                      isReadReceiptRequested: true
                      categories: {}
                      parentFolderId: '500123'
                      webLink: https://www.example.com
                      inferenceClassification: focused
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createMessage
      summary: Microsoft Office 365 Create Draft Message
      description: Create a draft of a new message in the signed-in user's mailbox. The draft can then be updated and sent. The message is saved in the Drafts folder by default. Requires Mail.ReadWrite permission.
      tags:
      - Mail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreateRequest'
            examples:
              CreatemessageRequestExample:
                summary: Default createMessage request
                x-microcks-default: true
                value:
                  subject: example_value
                  body:
                    contentType: text
                    content: example_value
                  toRecipients:
                  - {}
                  ccRecipients:
                  - {}
                  bccRecipients:
                  - {}
                  replyTo:
                  - {}
                  importance: low
                  isDeliveryReceiptRequested: true
                  isReadReceiptRequested: true
                  categories:
                  - example_value
      responses:
        '201':
          description: The created draft message object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Createmessage201Example:
                  summary: Default createMessage 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    sender: {}
                    from: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    conversationId: '500123'
                    conversationIndex: example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    importance: low
                    isRead: true
                    isDraft: true
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    flag:
                      flagStatus: notFlagged
                    categories:
                    - example_value
                    parentFolderId: '500123'
                    webLink: https://www.example.com
                    inferenceClassification: focused
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}:
    get:
      operationId: getMessage
      summary: Microsoft Office 365 Get Message
      description: Retrieve the properties and relationships of a message object. You can use $select to return specific properties and $expand to expand relationships such as attachments. Requires Mail.ReadBasic, Mail.Read, or Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: The requested message object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Getmessage200Example:
                  summary: Default getMessage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    sender: {}
                    from: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    conversationId: '500123'
                    conversationIndex: example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    importance: low
                    isRead: true
                    isDraft: true
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    flag:
                      flagStatus: notFlagged
                    categories:
                    - example_value
                    parentFolderId: '500123'
                    webLink: https://www.example.com
                    inferenceClassification: focused
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateMessage
      summary: Microsoft Office 365 Update Message
      description: Update the properties of a message object. Requires Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageUpdateRequest'
            examples:
              UpdatemessageRequestExample:
                summary: Default updateMessage request
                x-microcks-default: true
                value:
                  subject: example_value
                  body:
                    contentType: text
                    content: example_value
                  toRecipients:
                  - {}
                  ccRecipients:
                  - {}
                  bccRecipients:
                  - {}
                  importance: low
                  isRead: true
                  categories:
                  - example_value
                  flag:
                    flagStatus: notFlagged
                  inferenceClassification: focused
      responses:
        '200':
          description: The updated message object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Updatemessage200Example:
                  summary: Default updateMessage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    sender: {}
                    from: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    conversationId: '500123'
                    conversationIndex: example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    importance: low
                    isRead: true
                    isDraft: true
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    flag:
                      flagStatus: notFlagged
                    categories:
                    - example_value
                    parentFolderId: '500123'
                    webLink: https://www.example.com
                    inferenceClassification: focused
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMessage
      summary: Microsoft Office 365 Delete Message
      description: Delete a message in the signed-in user's mailbox. Requires Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - $ref: '#/components/parameters/messageId'
      responses:
        '204':
          description: Message deleted successfully. No content returned.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/sendMail:
    post:
      operationId: sendMail
      summary: Microsoft Office 365 Send Mail
      description: Send the message specified in the request body using either JSON or MIME format. The message is saved in the Sent Items folder by default. You can include an attachment with the send action. Requires Mail.Send permission.
      tags:
      - Mail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - message
              properties:
                message:
                  $ref: '#/components/schemas/MessageCreateRequest'
                saveToSentItems:
                  type: boolean
                  description: Whether to save the message in Sent Items folder.
                  default: true
            examples:
              SendmailRequestExample:
                summary: Default sendMail request
                x-microcks-default: true
                value:
                  message:
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    importance: low
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    categories:
                    - example_value
                  saveToSentItems: true
      responses:
        '202':
          description: Mail accepted for delivery. No content returned.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/mailFolders:
    get:
      operationId: listMailFolders
      summary: Microsoft Office 365 List Mail Folders
      description: Get the mail folder collection directly under the root folder of the signed-in user. The returned collection includes any mail search folders directly under the root. Requires Mail.ReadBasic, Mail.Read, or Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: A collection of mail folder objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailFolderCollectionResponse'
              examples:
                Listmailfolders200Example:
                  summary: Default listMailFolders 200 response
                  x-microcks-default: true
                  value:
                    '@odata.context': example_value
                    '@odata.nextLink': https://www.example.com
                    value:
                    - id: abc123
                      displayName: example_value
                      parentFolderId: '500123'
                      childFolderCount: 10
                      totalItemCount: 10
                      unreadItemCount: 10
                      isHidden: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/mailFolders/{mailFolder-id}/messages:
    get:
      operationId: listMailFolderMessages
      summary: Microsoft Office 365 List Messages in Folder
      description: Get the message collection in the specified mail folder. Requires Mail.ReadBasic, Mail.Read, or Mail.ReadWrite permission.
      tags:
      - Mail
      parameters:
      - name: mailFolder-id
        in: path
        required: true
        description: The unique identifier of the mail folder, or a well-known folder name (inbox, drafts, sentitems, deleteditems).
        schema:
          type: string
        example: '500123'
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: A collection of message objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageCollectionResponse'
              examples:
                Listmailfoldermessages200Example:
                  summary: Default listMailFolderMessages 200 response
                  x-microcks-default: true
                  value:
                    '@odata.context': example_value
                    '@odata.count': 10
                    '@odata.nextLink': https://www.example.com
                    value:
                    - id: abc123
                      subject: example_value
                      bodyPreview: example_value
                      toRecipients: {}
                      ccRecipients: {}
                      bccRecipients: {}
                      replyTo: {}
                      conversationId: '500123'
                      conversationIndex: example_value
                      receivedDateTime: '2026-01-15T10:30:00Z'
                      sentDateTime: '2026-01-15T10:30:00Z'
                      createdDateTime: '2026-01-15T10:30:00Z'
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      hasAttachments: true
                      internetMessageId: '500123'
                      importance: low
                      isRead: true
                      isDraft: true
                      isDeliveryReceiptRequested: true
                      isReadReceiptRequested: true
                      categories: {}
                      parentFolderId: '500123'
                      webLink: https://www.example.com
                      inferenceClassification: focused
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    search:
      name: $search
      in: query
      description: Search expression to filter results. Uses KQL syntax for directory objects.
      schema:
        type: string
    messageId:
      name: message-id
      in: path
      required: true
      description: The unique identifier of the message.
      schema:
        type: string
    count:
      name: $count
      in: query
      description: Include a count of the total number of items in a collection alongside the page of data values.
      schema:
        type: boolean
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties for sorting results.
      schema:
        type: string
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response.
      schema:
        type: string
    top:
      name: $top
      in: query
      description: The number of items to return in a result set. Maximum value depends on the API.
      schema:
        type: integer
        minimum: 1
    skip:
      name: $skip
      in: query
      description: The number of items to skip in the result set.
      schema:
        type: integer
        minimum: 0
    filter:
      name: $filter
      in: query
      description: OData filter expression to restrict the set of items returned.
      schema:
        type: string
    expand:
      name: $expand
      in: query
      description: Comma-separated list of relationships to expand and include in the response.
      schema:
        type: string
  schemas:
    ODataError:
      type: object
      description: The error response from the Microsoft Graph API following OData conventions.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The error code string.
            message:
              type: string
              description: A human-readable error message.
            innerError:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                request-id:
                  type: string
                client-request-id:
                  type: string
          example: example_value
    Message:
      type: object
      description: A message in a mailFolder. Contains the message subject, body, sender, recipients, and other metadata.
      properties:
        id:
          type: string
          readOnly: true
          description: Unique identifier for the message.
          example: abc123
        subject:
          type: string
          description: The subject of the message.
          example: example_value
        body:
          $ref: '#/components/schemas/ItemBody'
        bodyPreview:
          type: string
          readOnly: true
          description: The first 255 characters of the message body in text format.
          example: example_value
        sender:
          $ref: '#/components/schemas/Recipient'
        from:
          $ref: '#/components/schemas/Recipient'
        toRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          description: The To recipients for the message.
          example: []
        ccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          description: The Cc recipients for the message.
          example: []
        bccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          description: The Bcc recipients for the message.
          example: []
        replyTo:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          description: The email addresses to use when replying.
          example: []
        conversationId:
          type: string
          readOnly: true
          description: The ID of the conversation the email belongs to.
          example: '500123'
        conversationIndex:
          type: string
          format: byte
          readOnly: true
          description: The index of the message in the conversation.
          example: example_value
        receivedDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the message was received.
          example: '2026-01-15T10:30:00Z'
        sentDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the message was sent.
          example: '2026-01-15T10:30:00Z'
        createdDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the message was created.
          example: '2026-01-15T10:30:00Z'
        lastModifiedDateTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the message was last changed.
          example: '2026-01-15T10:30:00Z'
        hasAttachments:
          type: boolean
          readOnly: true
          description: Indicates whether the message has attachments.
          example: true
        internetMessageId:
          type: string
          readOnly: true
          description: The message ID in RFC2822 format.
          example: '500123'
        importance:
          type: string
          enum:
          - low
          - normal
          - high
          description: The importance of the message.
          example: low
        isRead:
          type: boolean
          description: Indicates whether the message has been read.
          example: true
        isDraft:
          type: boolean
          readOnly: true
          description: Indicates whether the message is a draft.
          example: true
        isDeliveryReceiptRequested:
          type: boolean
          description: Indicates whether a delivery receipt is requested.
          example: true
        isReadReceiptRequested:
          type: boolean
          description: Indicates whether a read receipt is requested.
          example: true
        flag:
          $ref: '#/components/schemas/FollowupFlag'
        categories:
          type: array
          items:
            type: string
          description: The categories associated with the message.
          example: []
        parentFolderId:
          type: string
          readOnly: true
          description: The unique identifier for the message's parent mailFolder.
          example: '500123'
        webLink:
          type: string
          format: uri
          readOnly: true
          description: The URL to open the message in Outlook on the web.
          example: https://www.example.com
        inferenceClassification:
          type: string
          enum:
          - focused
          - other
          description: The classification of the message based on inferred relevance.
          example: focused
    ItemBody:
      type: object
      description: Represents properties of the body of a message or event.
      properties:
        contentType:
          type: string
          enum:
          - text
          - html
          description: The type of the content. Possible values are text and html.
          example: text
        content:
          type: string
          description: The content of the item.
          example: example_value
    MessageUpdateRequest:
      type: object
      properties:
        subject:
          type: string
          example: example_value
        body:
          $ref: '#/components/schemas/ItemBody'
        toRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example: []
        ccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example: []
        bccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example: []
        importance:
          type: string
          enum:
          - low
          - normal
          - high
          example: low
        isRead:
          type: boolean
          example: true
        categories:
          type: array
          items:
            type: string
          example: []
        flag:
          $ref: '#/components/schemas/FollowupFlag'
        inferenceClassification:
          type: string
          enum:
          - focused
          - other
          example: focused
    DateTimeTimeZone:
      type: object
      description: Describes the date, time, and time zone of a point in time.
      properties:
        dateTime:
          type: string
          description: A single point of time in a combined date and time representation ({date}T{time}; for example, 2017-08-29T04:00:00.0000000).
          example: example_value
        timeZone:
          type: string
          description: The time zone for the time. For example, Pacific Standard Time. See https://learn.microsoft.com/en-us/graph/api/resources/datetimetimezone
          example: example_value
    FollowupFlag:
      type: object
      description: Allows setting a flag on an item for the user to follow up on later.
      properties:
        completedDateTime:
          $ref: '#/components/schemas/DateTimeTimeZone'
        dueDateTime:
          $ref: '#/components/schemas/DateTimeTimeZone'
        startDateTime:
          $ref: '#/components/schemas/DateTimeTimeZone'
        flagStatus:
          type: string
          enum:
          - notFlagged
          - complete
          - flagged
          description: The status of the follow-up flag.
          example: notFlagged
    MailFolderCollectionResponse:
      type: object
      properties:
        '@odata.context':
          type: string
          example: example_value
        '@odata.nextLink':
          type: string
          format: uri
          example: https://www.example.com
        value:
          type: array
          items:
            $ref: '#/components/schemas/MailFolder'
          example: []
    Recipient:
      type: object
      description: Represents information about a user in the sending or receiving end of a message or event.
      properties:
        emailAddress:
          $ref: '#/components/schemas/EmailAddress'
    MessageCreateRequest:
      type: object
      properties:
        subject:
          type: string
          description: The subject of the message.
          example: example_value
        body:
          $ref: '#/components/schemas/ItemBody'
        toRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example: []
        ccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/Recipient'
          example: []
        bccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/R

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-office-365/refs/heads/main/openapi/microsoft-office-365-mail-api-openapi.yml