GWS Gmail Action

Execute specific Gmail operations for sending, reading, and managing individual email messages.

When to Use This Command

Run this command when you need to:

• Send emails with attachments, CC/BCC recipients, and formatted HTML body content
• Read and parse specific email messages for data extraction or automated processing
• Manage drafts, threads, and message metadata like labels and read status

Consider alternatives when:

• You need to process emails in bulk where the auto command is more appropriate
• You are setting up forwarding or delegation which requires Gmail admin settings

Quick Start

Configuration

Copy
name: gws-gmail-action
type: command
category: google-workspace

Example Invocation

Copy
claude command:run gws-gmail-action --action send --to "[email protected]" --subject "Deploy Complete" --body "Version 2.5.0 deployed successfully."

Example Output

Composing email...
  From: [email protected]
  To: [email protected]
  Subject: Deploy Complete
  Body: plain text (41 characters)
  Attachments: none

Sending email...
  Message ID: msg_18f3a2b1c4d5
  Thread ID: thd_18f3a2b1c4d5
  Status: SENT

Delivery confirmed to [email protected]
  Timestamp: 2026-03-15 14:45:22 UTC

Core Concepts

Gmail Actions Overview

Aspect	Details
Send	Compose and send emails with HTML body, attachments, and recipients
Read	Fetch message content, headers, and attachments by message or thread ID
Reply	Reply to existing threads maintaining conversation context
Draft	Create, update, and send draft messages for review before delivery
Metadata	Modify labels, read status, star status, and importance markers

Email Send Workflow

Compose Message
  |    |    |
  v    v    v
To/CC Body  Attach
  |    |    |
  v    v    v
Build MIME Message
       |
       v
Validate Recipients
       |
       v
Send via Gmail API
       |
       v
Confirm Delivery
  (Message + Thread ID)

Configuration

Parameter	Type	Default	Description
action	string	(required)	Operation: send, read, reply, draft, modify
to	string	(none)	Recipient email addresses, comma-separated
subject	string	(none)	Email subject line
body	string	(none)	Message body text or path to HTML file
attachments	string[]	(none)	File paths for attachments to include

Best Practices

1. Use HTML for formatted emails - Point the body parameter to an HTML file for rich formatting. Plain text is fine for simple notifications but reports and updates benefit from structure.

2. Reply to threads instead of new emails - When responding to an existing conversation, use the reply action with the thread ID to keep the email chain intact for all participants.

3. Review drafts before sending - For important emails, create a draft first, review it in the Gmail interface, then send it from the command line or the web UI.

4. Keep attachment sizes reasonable - Gmail has a 25MB attachment limit. For larger files, upload to Drive and share a link in the email body instead. This approach also benefits recipients who may have mailbox size limits.

5. Use templates for recurring emails - If you send similar emails regularly, such as weekly status updates or deployment notifications, create message templates that can be filled with dynamic data each time rather than composing from scratch.

Common Issues

1. Send fails with authentication error - Ensure the Gmail API scope gmail.send is authorized. Re-authenticate with gws auth login --scopes gmail.send if the token has expired. Check that your OAuth client has not been revoked by the domain administrator.

2. HTML body renders as plain text - The body must be properly formatted MIME HTML. Specify --format html explicitly to ensure the message is sent with the correct content type headers. Verify the HTML is well-formed with proper opening and closing tags.

3. Attachments not received by recipient - Verify file paths are absolute and files exist. Some file types like .exe are blocked by Gmail security policies and will be silently stripped from the outgoing message without any error.

4. Reply lands in wrong thread - When using the reply action, ensure you provide the correct thread ID, not just the message ID. Replying with an incorrect thread ID creates a new thread instead of continuing the existing conversation.

5. Email appears in spam for recipients - Programmatically sent emails may trigger spam filters, especially if the body contains many links or the sending domain lacks proper SPF, DKIM, and DMARC records. Work with your domain administrator to ensure email authentication is properly configured.