Skip to content

gws-setup-guide.md

Latest commit

 

History

History
249 lines (164 loc) · 8.61 KB

gws-setup-guide.md

File metadata and controls

249 lines (164 loc) · 8.61 KB

Setting Up Email Backends for the Postman Agent

The Postman agent supports three email backends. You can use one or more:

Backend Email Provider Access Level Calendar
GWS CLI (gws) Gmail / Google Workspace Full read/write Yes (Google Calendar)
Hey CLI (hey) Hey.com Full read/write No (Hey has its own productivity tools, not Google Calendar)
MCP connectors Gmail Read-only + drafts Read-only (Google Calendar)

If you have both Gmail and Hey.com, you can use gws and hey simultaneously. Set your preferred primary backend in Meta/user-profile.md with email_backend: hey or email_backend: gws (default: gws).

Option A: Hey CLI (for Hey.com users)

Step 1: Install Hey CLI

# See https://github.com/basecamp/hey-cli for the latest instructions
gem install hey-cli

Step 2: Authenticate

hey auth login

Step 3: Verify

hey auth status --json
hey box imbox --json --limit 1

If both return JSON, you're good. The Postman will auto-detect hey on PATH.

Troubleshooting Hey

  • hey: command not found: ensure the gem bin directory is on your PATH. Check with gem environment and add <gem_dir>/bin to PATH.
  • Auth expired: run hey auth refresh or hey auth login.
  • General issues: run hey doctor for diagnostics.

Option B: Google Workspace CLI (for Gmail users)

The Postman agent uses the Google Workspace CLI (gws) to interact with Gmail and Google Calendar. This gives the agent full read/write access — searching, reading, archiving, deleting, labelling emails, and creating/modifying calendar events.

Why gws instead of MCP?

The Anthropic-hosted MCP servers for Gmail and Calendar are read-only (plus draft creation). They cannot archive, delete, label, or send emails. The Google Workspace CLI wraps the full Google API surface, giving the Postman agent the ability to actually manage your inbox — not just read it.

Prerequisites

  • Node.js (v18+) and npm
  • Optional: Google Cloud SDK (gcloud) — only needed if you prefer CLI-based project setup instead of the Cloud Console UI
  • A Google account (personal Gmail works fine)

Step 1: Install the Google Workspace CLI

npm install -g @googleworkspace/cli

Verify:

gws --version

Step 2: Install Google Cloud SDK (if not already installed)

macOS (Apple Silicon)

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
tar -xf google-cloud-cli-darwin-arm.tar.gz
./google-cloud-sdk/install.sh

macOS (Intel)

curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
tar -xf google-cloud-cli-darwin-x86_64.tar.gz
./google-cloud-sdk/install.sh

Other platforms

See https://cloud.google.com/sdk/docs/install

After installation, restart your terminal so the new PATH takes effect. If you don't want to restart, you can source your profile manually:

source ~/.zshrc   # or ~/.bashrc

Verify:

gcloud --version

Step 3: Create a Google Cloud project

  1. Go to https://console.cloud.google.com/
  2. Create a new project (e.g., my-vault)
  3. Note the project ID — you'll need it below

Step 4: Configure the OAuth consent screen

  1. Go to APIs & Services > OAuth consent screen in your project: https://console.cloud.google.com/apis/credentials/consent?project=YOUR_PROJECT_ID
  2. Choose External as User Type (the only option for personal Gmail accounts)
  3. Fill in the required fields:
    • App name: anything (e.g., "Vault CLI")
    • User support email: your email
    • Developer contact: your email
  4. Click through the remaining screens (scopes, test users) and save

Important — Add yourself as a test user:

  1. Back on the OAuth consent screen, find the Audience section
  2. Under Test users, click Add users
  3. Enter your Gmail address and save

This step is easy to miss and you will get an "Access blocked" error without it. Unverified apps can only be used by explicitly listed test users.

Step 5: Create OAuth credentials

  1. Go to APIs & Services > Credentials: https://console.cloud.google.com/apis/credentials?project=YOUR_PROJECT_ID
  2. Click Create Credentials > OAuth client ID
  3. Application type: Desktop app
  4. Name: anything (e.g., "gws-cli")
  5. Click Create
  6. Copy the Client ID and Client Secret

Step 6: Set up gws authentication

gws auth setup

When prompted, paste your Client ID and Client Secret.

Step 7: Log in and select scopes

gws auth login

This opens an interactive scope selector. Deselect everything and only keep:

  • https://www.googleapis.com/auth/gmail.modify — read/write/archive/delete emails
  • https://www.googleapis.com/auth/gmail.send — send emails and drafts
  • https://www.googleapis.com/auth/calendar.events — create/update/delete calendar events
  • https://www.googleapis.com/auth/calendar.calendarlist.readonly — list available calendars

Optionally also keep:

  • https://www.googleapis.com/auth/drive — if you want Drive access
  • https://www.googleapis.com/auth/tasks — if you want Tasks access
  • openid, userinfo.email, userinfo.profile — for profile info

Do not select all 85+ scopes. Google will reject the auth request for unverified apps with too many scopes, especially admin/workspace scopes that aren't available to personal accounts.

After selecting scopes, a browser window opens. Sign in with your Google account. You may see a "This app isn't verified" warning — click Continue (this is expected for personal-use OAuth apps).

On success you'll see:

Authentication successful. Encrypted credentials saved.

Step 8: Verify it works

Test Gmail access:

gws gmail users messages list --params '{"userId": "me", "maxResults": 3}'

Test Calendar access:

gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-03-01T00:00:00Z", "maxResults": 3}'

Both should return JSON results.

Step 9: Remove MCP servers (optional)

If your .mcp.json still has the Anthropic-hosted Gmail/Calendar servers, you can remove them. Remove only the gmail and google-calendar entries from your .mcp.json, leaving any other MCP servers intact.

If .mcp.json contained only those two servers, you can delete the file entirely.

Troubleshooting

"Access blocked" / Error 403

You haven't added yourself as a test user. Go back to Step 4, point 5-7.

"invalid_scope" / Error 400

You selected too many scopes, including ones not available to personal Gmail accounts (e.g., admin, classroom, chat). Re-run gws auth login and select only the scopes listed in Step 7.

"gcloud CLI not found"

The Google Cloud SDK isn't on your PATH. Restart your terminal. If you don't want to restart, run:

source ~/google-cloud-sdk/path.zsh.inc   # adjust path if installed elsewhere

gws command not found

Restart your terminal first — this resolves most cases. If it still fails, the npm global bin directory may not be on your PATH. Check with:

npm config get prefix

And ensure <prefix>/bin is in your PATH.

"Using keyring backend: keyring" warning

This is normal — gws stores encrypted credentials in your OS keyring. Not an error.

How it works in the Postman agent

The Postman agent calls gws commands via the Bash tool. Key operations:

Operation Command
Search inbox gws gmail users messages list --params '{"userId": "me", "q": "..."}'
Read email gws gmail users messages get --params '{"userId": "me", "id": "ID", "format": "full"}'
Read thread gws gmail users threads get --params '{"userId": "me", "id": "ID"}'
Mark as read gws gmail users messages modify --params '{"userId": "me", "id": "ID"}' --json '{"removeLabelIds": ["UNREAD"]}'
Archive gws gmail users messages modify --params '{"userId": "me", "id": "ID"}' --json '{"removeLabelIds": ["INBOX"]}'
Trash gws gmail users messages trash --params '{"userId": "me", "id": "ID"}'
List events gws calendar events list --params '{"calendarId": "primary", "timeMin": "...", "timeMax": "..."}'
Create event gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "...", ...}'
Create draft gws gmail users drafts create --params '{"userId": "me"}' --json '{"message": {"raw": "BASE64"}}'

All commands return JSON. The --params flag is for URL/query parameters; --json is for the request body.