Gmail Send (gws-gmail-send)
PREREQUISITE: Read the
gws-sharedskill for auth, global flags, and security rules.
Send emails quickly using the gws gmail +send helper.
Usage
gws gmail +send --to <EMAILS> --subject <SUBJECT> --body <TEXT>
Flags
| Flag | Required | Description |
|---|---|---|
--to |
✓ | Recipient email address(es), comma-separated |
--subject |
✓ | Email subject line |
--body |
✓ | Email body (plain text, or HTML when --html is set) |
--cc |
— | CC email address(es), comma-separated |
--bcc |
— | BCC email address(es), comma-separated |
--html |
— | Treat --body as HTML content |
--dry-run |
— | Show the request that would be sent, without executing |
Examples
# Simple plain-text email
gws gmail +send \
--to alice@example.com \
--subject 'Hello from gws' \
--body 'Hi Alice! This was sent by the gws CLI.'
# HTML email
gws gmail +send \
--to alice@example.com \
--subject 'Your report is ready' \
--body '<h1>Report Ready</h1><p>Click <a href="https://example.com">here</a> to view.</p>' \
--html
# With CC and BCC
gws gmail +send \
--to alice@example.com \
--subject 'Project Update' \
--body 'See the attached notes.' \
--cc bob@example.com \
--bcc manager@example.com
# Preview without sending
gws gmail +send \
--to alice@example.com \
--subject 'Test' \
--body 'Hello' \
--dry-run
# Send to multiple recipients
gws gmail +send \
--to 'alice@example.com,bob@example.com,carol@example.com' \
--subject 'Team announcement' \
--body 'The sprint review is tomorrow at 2pm.'
Using the Raw API (for attachments)
The +send helper does not support file attachments. Use the raw messages.send API with a multipart MIME message for attachments:
# Base64-encode an RFC 2822 message with attachment
# (compose the MIME message first, then base64-encode it)
gws gmail users messages send \
--params '{"userId": "me"}' \
--json '{"raw": "<base64url-encoded-mime-message>"}'
[!CAUTION] This is a write command. Always confirm with the user before sending an email. Use
--dry-runto preview the request first.
Tips
- Handles RFC 2822 formatting and base64url encoding automatically
- For threading (replies), use
gws gmail +replyinstead (seegws-gmailskill) - For bulk email, loop over recipients and add delays to avoid rate limits
- Always include a meaningful subject — blank subjects are marked as spam
See Also
gws-gmail— Full Gmail API reference (threads, labels, filters, drafts)gws-shared— Authentication and global flags