Microsoft Graph Mail API

openapi: 3.1.0
info:
  title: Microsoft Outlook Microsoft Graph Mail API
  description: >-
    API for accessing Outlook email messages, mail folders, and attachments
    through Microsoft Graph. Provides full CRUD operations on messages,
    mail folder management, attachment handling, and message actions such
    as send, reply, forward, copy, and move.
  version: 1.0.0
  contact:
    name: Microsoft Graph Support
    url: https://developer.microsoft.com/en-us/graph/support
  license:
    name: Microsoft API Terms of Use
    url: https://learn.microsoft.com/en-us/legal/microsoft-apis/terms-of-use
  x-api-id: microsoft-graph-mail
  x-audience: external

servers:
- url: https://graph.microsoft.com/v1.0
  description: Microsoft Graph v1.0 production endpoint

security:
- oauth2: []

tags:
- name: Attachments
  description: Operations on message attachments

- name: Mail Folders
  description: Operations on mail folders in a user mailbox
- name: Messages
  description: Operations on email messages in a user mailbox
paths:
  /me/messages:
    get:
      operationId: listMessages
      summary: Microsoft Outlook List Messages
      description: >-
        Get all the messages in the signed-in user's mailbox including the
        Deleted Items and Clutter folders. Supports OData query parameters
        including $filter, $select, $top, $skip, $orderby, and $count.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/top'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/orderby'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: Successfully retrieved messages.
          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
                      createdDateTime: '2026-01-15T10:30:00Z'
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      changeKey: example_value
                      categories: {}
                      receivedDateTime: '2026-01-15T10:30:00Z'
                      sentDateTime: '2026-01-15T10:30:00Z'
                      hasAttachments: true
                      internetMessageId: '500123'
                      internetMessageHeaders: {}
                      subject: example_value
                      bodyPreview: example_value
                      importance: low
                      parentFolderId: '500123'
                      conversationId: '500123'
                      conversationIndex: example_value
                      isDeliveryReceiptRequested: true
                      isReadReceiptRequested: true
                      isRead: true
                      isDraft: true
                      webLink: https://www.example.com
                      inferenceClassification: focused
                      toRecipients: {}
                      ccRecipients: {}
                      bccRecipients: {}
                      replyTo: {}
                      attachments: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDraftMessage
      summary: Microsoft Outlook Create Draft Message
      description: >-
        Create a draft of a new message in the signed-in user's mailbox.
        The message is saved in the Drafts folder. You can then update or
        send the draft.
      tags:
      - Messages
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
            examples:
              CreatedraftmessageRequestExample:
                summary: Default createDraftMessage request
                x-microcks-default: true
                value:
                  id: abc123
                  createdDateTime: '2026-01-15T10:30:00Z'
                  lastModifiedDateTime: '2026-01-15T10:30:00Z'
                  changeKey: example_value
                  categories:
                  - example_value
                  receivedDateTime: '2026-01-15T10:30:00Z'
                  sentDateTime: '2026-01-15T10:30:00Z'
                  hasAttachments: true
                  internetMessageId: '500123'
                  internetMessageHeaders:
                  - name: Example Title
                    value: example_value
                  subject: example_value
                  body:
                    contentType: text
                    content: example_value
                  bodyPreview: example_value
                  importance: low
                  parentFolderId: '500123'
                  conversationId: '500123'
                  conversationIndex: example_value
                  isDeliveryReceiptRequested: true
                  isReadReceiptRequested: true
                  isRead: true
                  isDraft: true
                  webLink: https://www.example.com
                  inferenceClassification: focused
                  flag:
                    flagStatus: notFlagged
                  from: {}
                  sender: {}
                  toRecipients:
                  - {}
                  ccRecipients:
                  - {}
                  bccRecipients:
                  - {}
                  replyTo:
                  - {}
                  uniqueBody:
                    contentType: text
                    content: example_value
                  attachments:
                  - '@odata.type': '#microsoft.graph.fileAttachment'
                    id: abc123
                    name: Example Title
                    contentType: example_value
                    size: 10
                    isInline: true
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    contentBytes: example_value
                    contentId: '500123'
                    contentLocation: example_value
      responses:
        '201':
          description: Successfully created draft message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Createdraftmessage201Example:
                  summary: Default createDraftMessage 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - name: Example Title
                      value: example_value
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - '@odata.type': '#microsoft.graph.fileAttachment'
                      id: abc123
                      name: Example Title
                      contentType: example_value
                      size: 10
                      isInline: true
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      contentBytes: example_value
                      contentId: '500123'
                      contentLocation: example_value
        '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 Outlook Get Message
      description: >-
        Read the properties and relationships of a message object. Supports
        $select and $expand query parameters. Use $select=internetMessageHeaders
        to get custom internet message headers.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      - $ref: '#/components/parameters/select'
      responses:
        '200':
          description: Successfully retrieved message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Getmessage200Example:
                  summary: Default getMessage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - name: Example Title
                      value: example_value
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - '@odata.type': '#microsoft.graph.fileAttachment'
                      id: abc123
                      name: Example Title
                      contentType: example_value
                      size: 10
                      isInline: true
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      contentBytes: example_value
                      contentId: '500123'
                      contentLocation: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateMessage
      summary: Microsoft Outlook Update Message
      description: >-
        Update the properties of a message object. Only draft messages can
        have their toRecipients, ccRecipients, bccRecipients, subject, body,
        and other content properties updated. Sent messages can have isRead
        and categories updated.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
            examples:
              UpdatemessageRequestExample:
                summary: Default updateMessage request
                x-microcks-default: true
                value:
                  id: abc123
                  createdDateTime: '2026-01-15T10:30:00Z'
                  lastModifiedDateTime: '2026-01-15T10:30:00Z'
                  changeKey: example_value
                  categories:
                  - example_value
                  receivedDateTime: '2026-01-15T10:30:00Z'
                  sentDateTime: '2026-01-15T10:30:00Z'
                  hasAttachments: true
                  internetMessageId: '500123'
                  internetMessageHeaders:
                  - name: Example Title
                    value: example_value
                  subject: example_value
                  body:
                    contentType: text
                    content: example_value
                  bodyPreview: example_value
                  importance: low
                  parentFolderId: '500123'
                  conversationId: '500123'
                  conversationIndex: example_value
                  isDeliveryReceiptRequested: true
                  isReadReceiptRequested: true
                  isRead: true
                  isDraft: true
                  webLink: https://www.example.com
                  inferenceClassification: focused
                  flag:
                    flagStatus: notFlagged
                  from: {}
                  sender: {}
                  toRecipients:
                  - {}
                  ccRecipients:
                  - {}
                  bccRecipients:
                  - {}
                  replyTo:
                  - {}
                  uniqueBody:
                    contentType: text
                    content: example_value
                  attachments:
                  - '@odata.type': '#microsoft.graph.fileAttachment'
                    id: abc123
                    name: Example Title
                    contentType: example_value
                    size: 10
                    isInline: true
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    contentBytes: example_value
                    contentId: '500123'
                    contentLocation: example_value
      responses:
        '200':
          description: Successfully updated message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Updatemessage200Example:
                  summary: Default updateMessage 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - name: Example Title
                      value: example_value
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - '@odata.type': '#microsoft.graph.fileAttachment'
                      id: abc123
                      name: Example Title
                      contentType: example_value
                      size: 10
                      isInline: true
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      contentBytes: example_value
                      contentId: '500123'
                      contentLocation: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteMessage
      summary: Microsoft Outlook Delete Message
      description: >-
        Delete a message in the specified user's mailbox. The message is moved
        to the Deleted Items folder.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      responses:
        '204':
          description: Successfully deleted message.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}/send:
    post:
      operationId: sendDraftMessage
      summary: Microsoft Outlook Send Draft Message
      description: >-
        Send a previously created message draft. The message is then saved
        in the Sent Items folder.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      responses:
        '202':
          description: Accepted. The message is queued for sending.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}/copy:
    post:
      operationId: copyMessage
      summary: Microsoft Outlook Copy Message
      description: >-
        Copy a message to a folder within the user's mailbox.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destinationId:
                  type: string
                  description: The destination folder ID or well-known folder name.
              required:
              - destinationId
            examples:
              CopymessageRequestExample:
                summary: Default copyMessage request
                x-microcks-default: true
                value:
                  destinationId: '500123'
      responses:
        '201':
          description: Successfully copied message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Copymessage201Example:
                  summary: Default copyMessage 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - name: Example Title
                      value: example_value
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - '@odata.type': '#microsoft.graph.fileAttachment'
                      id: abc123
                      name: Example Title
                      contentType: example_value
                      size: 10
                      isInline: true
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      contentBytes: example_value
                      contentId: '500123'
                      contentLocation: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}/move:
    post:
      operationId: moveMessage
      summary: Microsoft Outlook Move Message
      description: >-
        Move a message to a different folder within the user's mailbox. This
        creates a new copy of the message in the destination folder and removes
        the original message.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                destinationId:
                  type: string
                  description: The destination folder ID or well-known folder name.
              required:
              - destinationId
            examples:
              MovemessageRequestExample:
                summary: Default moveMessage request
                x-microcks-default: true
                value:
                  destinationId: '500123'
      responses:
        '201':
          description: Successfully moved message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                Movemessage201Example:
                  summary: Default moveMessage 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - name: Example Title
                      value: example_value
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - '@odata.type': '#microsoft.graph.fileAttachment'
                      id: abc123
                      name: Example Title
                      contentType: example_value
                      size: 10
                      isInline: true
                      lastModifiedDateTime: '2026-01-15T10:30:00Z'
                      contentBytes: example_value
                      contentId: '500123'
                      contentLocation: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}/reply:
    post:
      operationId: replyToMessage
      summary: Microsoft Outlook Reply to Message
      description: >-
        Reply to the sender of a message using either JSON or MIME format.
        The message is then saved in the Sent Items folder.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  $ref: '#/components/schemas/Message'
                comment:
                  type: string
                  description: A comment to include with the reply.
            examples:
              ReplytomessageRequestExample:
                summary: Default replyToMessage request
                x-microcks-default: true
                value:
                  message:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-15T10:30:00Z'
                    hasAttachments: true
                    internetMessageId: '500123'
                    internetMessageHeaders:
                    - {}
                    subject: example_value
                    body:
                      contentType: text
                      content: example_value
                    bodyPreview: example_value
                    importance: low
                    parentFolderId: '500123'
                    conversationId: '500123'
                    conversationIndex: example_value
                    isDeliveryReceiptRequested: true
                    isReadReceiptRequested: true
                    isRead: true
                    isDraft: true
                    webLink: https://www.example.com
                    inferenceClassification: focused
                    flag:
                      flagStatus: notFlagged
                    from: {}
                    sender: {}
                    toRecipients:
                    - {}
                    ccRecipients:
                    - {}
                    bccRecipients:
                    - {}
                    replyTo:
                    - {}
                    uniqueBody:
                      contentType: text
                      content: example_value
                    attachments:
                    - {}
                  comment: example_value
      responses:
        '202':
          description: Accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'

      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /me/messages/{message-id}/replyAll:
    post:
      operationId: replyAllToMessage
      summary: Microsoft Outlook Reply All to Message
      description: >-
        Reply to all recipients of a message. The message is then saved in
        the Sent Items folder.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/messageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  $ref: '#/components/schemas/Message'
                comment:
                  type: string
                  description: A comment to include with the reply.
            examples:
              ReplyalltomessageRequestExample:
                summary: Default replyAllToMessage request
                x-microcks-default: true
                value:
                  message:
                    id: abc123
                    createdDateTime: '2026-01-15T10:30:00Z'
                    lastModifiedDateTime: '2026-01-15T10:30:00Z'
                    changeKey: example_value
                    categories:
                    - example_value
                    receivedDateTime: '2026-01-15T10:30:00Z'
                    sentDateTime: '2026-01-

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