Gmail Port

Purpose

This is the reference integration for Harbor http_api Action Model authoring.

Use it when:

• building Gmail actions in Harbor
• extending the Dock / Hub Gmail entry
• teaching Codex or OpenClaw how to map a real API into Harbor Ports and Harbor Actions

Harbor Port worksheet

Product

• Product: Gmail API
• Publisher slug: google
• Publisher name: Google
• Category: Email
• Tags: google, gmail, email, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Gmail API
• Description: Gmail API connection managed locally through Harbor.
• Base URL: https://gmail.googleapis.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

Gmail is a good Harbor fit when we stay on fixed /users/me/... routes and keep write payloads in input.body. For future bounded writes, keep request data in input.body and keep any filter-like values explicit rather than stringly-typed.

Good Harbor Gmail actions:

• stable GET list/read routes
• explicit POST routes for draft/create/send flows
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for bounded writes
• resultMode: "json_summary" for all starter actions

Avoid for now:

• path-parameter-heavy actions that need arbitrary message ids
• query-string-specific search actions
• giant unrestricted mail admin surfaces
• automatic publish of broad write actions

Starter Gmail actions

Automatic read actions

• get-profile -> GET /gmail/v1/users/me/profile
• list-labels -> GET /gmail/v1/users/me/labels
• list-messages -> GET /gmail/v1/users/me/messages
• list-threads -> GET /gmail/v1/users/me/threads
• list-drafts -> GET /gmail/v1/users/me/drafts
• list-send-as-identities -> GET /gmail/v1/users/me/settings/sendAs
• list-forwarding-addresses -> GET /gmail/v1/users/me/settings/forwardingAddresses
• list-filters -> GET /gmail/v1/users/me/settings/filters
• get-auto-forwarding -> GET /gmail/v1/users/me/settings/autoForwarding
• get-imap-settings -> GET /gmail/v1/users/me/settings/imap
• get-language-settings -> GET /gmail/v1/users/me/settings/language
• get-pop-settings -> GET /gmail/v1/users/me/settings/pop
• get-vacation-settings -> GET /gmail/v1/users/me/settings/vacation

Approval-friendly write actions

• create-draft -> POST /gmail/v1/users/me/drafts
• send-message -> POST /gmail/v1/users/me/messages/send
• create-label -> POST /gmail/v1/users/me/labels
• create-filter -> POST /gmail/v1/users/me/settings/filters
• create-forwarding-address -> POST /gmail/v1/users/me/settings/forwardingAddresses

Why these actions

These routes fit Harbor's Action Model well because they:

• stay under one fixed Gmail API origin
• use fixed paths relative to the Harbor Port
• do not require arbitrary full URLs
• can be reviewed as named capabilities
• keep hidden auth entirely local to Harbor Node

Suggested operator workflow

1. Import the Gmail Dock entry from Dock / Hub.
2. Configure the local Gmail bearer token in Harbor Node.
3. Use the imported live action set immediately for low-risk reads after local auth is configured.
4. Keep send/create actions on require_approval unless there is a very deliberate local policy reason not to.
5. Create new drafts only when you want to extend the imported Gmail surface beyond the Dock starter set.

Suggested agent workflow

1. Inspect the existing Gmail 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 Gmail auth
• widen Gmail into a generic arbitrary proxy

Current update strategy

For now, Gmail updates are manual:

• update the Dock / Hub Gmail integration document in apps/hub/catalog/integrations/google/gmail.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as a gmail:latest background sync or a manual "check for Hub updates" flow are intentionally deferred until Harbor has clearer version and update semantics.

Official reference starting points

• Gmail API reference root: https://developers.google.com/workspace/gmail/api/reference/rest
• Gmail profile: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users/getProfile
• Gmail labels list: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.labels/list
• Gmail messages list: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list
• Gmail threads list: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.threads/list
• Gmail drafts list: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/list
• Gmail send message: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/send
• Gmail create draft: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.drafts/create
• Gmail send-as list: https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.settings.sendAs/list