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-gmail-forward
Forward Gmail messages to new recipients with optional notes and attachments.
gws-gmail-read
Read Gmail messages and extract body or headers with automatic HTML-to-text conversion.
gws-gmail-reply
Reply to Gmail messages with automatic threading, CC/BCC, attachments, and draft support.
gws-gmail-reply-all
Reply-all to Gmail messages with automatic threading and flexible recipient control.
gws-gmail-send
Send emails via Gmail with attachments, CC/BCC, HTML support, and draft options.
gws-gmail-triage
Quickly view your unread Gmail inbox with sender, subject, and date.