Microsoft Graph Mail Port

Purpose

This is the Harbor reference integration for Microsoft Graph Mail.

Use it when:

• building Microsoft Graph Mail actions in Harbor
• extending the Dock / Hub Microsoft Graph Mail entry
• teaching Codex or OpenClaw how to map a mailbox API into Harbor Ports and Harbor Actions without turning Harbor into a generic mail proxy

Harbor Port worksheet

Product

• Product: Microsoft Graph Mail
• Publisher slug: microsoft
• Publisher name: Microsoft
• Category: Email
• Tags: microsoft, graph, mail, email, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Microsoft Graph Mail API
• Description: Microsoft Graph Mail connection managed locally through Harbor.
• Base URL: https://graph.microsoft.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Microsoft Graph Mail is a good Harbor fit today when we stay on signed-in-user /me routes.

Good Harbor Microsoft Graph Mail actions:

• stable GET routes for signed-in user profile and mailbox listing
• one explicit POST route for sendMail
• typed query input for mailbox page size
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for send flows
• resultMode: "json_summary" for all starter actions

Avoid for now:

• arbitrary folder traversal with freeform folder IDs
• broad mailbox mutation surfaces such as delete, move, patch, and draft management
• raw header customization beyond the standard Harbor-managed auth header
• automatic publish of send actions

Starter Microsoft Graph Mail actions

Automatic read actions

• get-profile -> GET /v1.0/me
• list-messages -> GET /v1.0/me/messages

Approval-friendly write actions

• send-mail -> POST /v1.0/me/sendMail

Why these actions

These routes fit Harbor's current safe model well because they:

• stay under one fixed Microsoft Graph API origin
• use fixed signed-in-user paths relative to the Harbor Port
• keep query parameters typed and reviewable through Harbor's Action Model
• keep hidden auth entirely local to Harbor Node
• avoid arbitrary full URL editing and raw query-string injection
• can be reviewed as named capabilities before publish

Action Model notes

For Microsoft Graph Mail actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /v1.0/me
• /v1.0/me/messages
• /v1.0/me/sendMail

At execution time, callers supply values by location:

• input.query for typed query parameters
• input.body for JSON write payloads

Example mailbox listing request:

{
  "query": {
    "$top": 25
  }
}

Example sendMail request:

{
  "body": {
    "message": {
      "subject": "Meet for lunch?",
      "body": {
        "contentType": "Text",
        "content": "The new cafeteria is open."
      },
      "toRecipients": [
        {
          "emailAddress": {
            "address": "alex@example.com"
          }
        }
      ]
    },
    "saveToSentItems": false
  }
}

Harbor applies the fixed route, validates the typed inputs, and keeps the underlying access token hidden.

Suggested operator workflow

1. Import the Microsoft Graph Mail Dock entry from Dock / Hub.
2. Configure the local Microsoft Graph bearer token in Harbor Node.
3. Use get-profile first to verify the connection.
4. Use list-messages with a small $top value to confirm mailbox access.
5. Keep send-mail on require_approval unless there is a very deliberate local policy reason not to.

Suggested agent workflow

1. Inspect the existing Microsoft Graph Mail Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path actions only.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Microsoft Graph auth
• widen Microsoft Graph Mail into a generic arbitrary proxy

Current update strategy

For now, Microsoft Graph Mail updates are manual:

• update the Dock / Hub Microsoft Graph Mail integration document in apps/hub/catalog/integrations/microsoft/microsoft-graph-mail.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Official reference starting points

• Microsoft Graph overview: https://learn.microsoft.com/en-us/graph/api/overview?view=graph-rest-1.0
• Get signed-in user: https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0
• List messages: https://learn.microsoft.com/en-us/graph/api/user-list-messages?view=graph-rest-1.0
• Send mail: https://learn.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0