gws-gmail
googleworkspace/cli
Send, read, and manage Gmail emails via Google Workspace CLI.
What is gws-gmail?
Gmail skill for Google Workspace CLI enables sending, reading, and managing emails programmatically. Use it to automate email workflows, triage inboxes, reply to messages, and access Gmail API resources.
- Send emails with attachments and formatting
- Read message bodies and extract headers
- Reply, reply-all, and forward messages with automatic threading
- Triage unread inbox with sender, subject, and date summaries
- Watch mailbox for new incoming emails in real-time
- Manage drafts, labels, threads, and email history
How to install gws-gmail
npx skills add null --skill gws-gmail- Google Workspace CLI (gws) installed
- gws-shared skill installed (for authentication and global flags)
- Google Workspace account with Gmail enabled
- Proper OAuth scopes configured for Gmail API access
How to use gws-gmail
- 1.Install the skill: npx skills add null --skill gws-gmail
- 2.Review gws-shared/SKILL.md for authentication setup and security rules
- 3.Run gws gmail --help to browse available resources and methods
- 4.Use gws schema gmail.<resource>.<method> to inspect required parameters and types
- 5.Call helper commands (+send, +triage, +reply, +read, +watch) for common tasks or use raw API methods with --params and --json flags
- 6.Set up push notifications with +watch or users.watch for real-time email monitoring
Use cases
- Automate email notifications and alerts from your application
- Build inbox triage workflows to summarize unread messages
- Create email-based approval or notification systems
- Forward or reply to messages programmatically based on conditions
- Monitor mailbox for specific incoming emails
- Automation engineers
- Productivity workflow builders
- Google Workspace administrators
- Developers integrating email into agent workflows
gws-gmail FAQ
Gmail skill requires Google Workspace authentication configured in gws-shared. See ../gws-shared/SKILL.md for setup and security rules.
Yes, the +send helper command supports sending emails with attachments and formatting.
Use the +watch helper command or users.watch API method to set up push notifications and stream new emails as NDJSON.
+reply responds only to the sender, while +reply-all includes all original recipients. Both handle threading automatically.
Run gws gmail --help to browse resources, then use gws schema gmail.<resource>.<method> to inspect parameters and types.
Full instructions (SKILL.md)
Source of truth, from googleworkspace/cli.
name: gws-gmail description: "Gmail: Send, read, and manage email." metadata: version: 0.22.5 openclaw: category: "productivity" requires: bins: - gws cliHelp: "gws gmail --help"
gmail (v1)
PREREQUISITE: Read
../gws-shared/SKILL.mdfor auth, global flags, and security rules. If missing, rungws generate-skillsto create it.
gws gmail <resource> <method> [flags]
Helper Commands
| Command | Description |
|---|---|
+send | Send an email |
+triage | Show unread inbox summary (sender, subject, date) |
+reply | Reply to a message (handles threading automatically) |
+reply-all | Reply-all to a message (handles threading automatically) |
+forward | Forward a message to new recipients |
+read | Read a message and extract its body or headers |
+watch | Watch for new emails and stream them as NDJSON |
API Resources
users
getProfile— Gets the current user's Gmail profile.stop— Stop receiving push notifications for the given user mailbox.watch— Set up or update a push notification watch on the given user mailbox.drafts— Operations on the 'drafts' resourcehistory— Operations on the 'history' resourcelabels— Operations on the 'labels' resourcemessages— Operations on the 'messages' resourcesettings— Operations on the 'settings' resourcethreads— Operations on the 'threads' resource
Discovering Commands
Before calling any API method, inspect it:
# Browse resources and methods
gws gmail --help
# Inspect a method's required params, types, and defaults
gws schema gmail.<resource>.<method>
Use gws schema output to build your --params and --json flags.
Related skills
More from googleworkspace/cli and the wider catalog.
gws-drive
Manage Google Drive files, folders, and shared drives via CLI.
gws-docs
Read and write Google Docs via command line.
gws-calendar
Manage Google Calendar events, calendars, and access control via CLI.
gws-sheets
Read and write Google Sheets spreadsheets via CLI.
gws-gmail-send
Send emails via Gmail with attachments, CC/BCC, HTML support, and draft options.
gws-docs-write
Append plain text to the end of a Google Docs document.