Skip to main content

​
Overview

The Gmail API provides access to Gmail mailboxes and allows you to send email, manage drafts, labels, threads, and more. API Name: gmail
Version: v1
Official Documentation: Gmail API Reference

​
Common Resources

​
Messages

Send, read, and manage email messages.
​
userId
string
required
The user’s email address or me for the authenticated user
​
id
string
The message ID
​
q
string
Gmail search query (e.g., "is:unread from:boss@example.com")
​
maxResults
integer
Maximum number of messages to return (default: 100, max: 500)

​
Labels

Organize messages with labels.
​
userId
string
required
The user’s email address or me
​
id
string
The label ID
​
name
string
The display name of the label

​
Drafts

Create and manage draft messages.
​
userId
string
required
The user’s email address or me
​
id
string
The draft ID

​
Common Methods

​
List Messages

gws gmail users messages list \
  --params '{"userId": "me", "maxResults": 10}'
​
messages
array
Array of message objects
​
id
string
The message ID
​
threadId
string
The thread ID this message belongs to

​
Get Message

gws gmail users messages get \
  --params '{"userId": "me", "id": "18d1e2f3a4b5c6d7"}'

​
Send Email

echo -e "To: recipient@example.com\nSubject: Hello\n\nMessage body" | \
  base64 | \
  gws gmail users messages send \
    --params '{"userId": "me"}' \
    --json '{"raw": "<base64-encoded-message>"}'

​
Search Messages

gws gmail users messages list --params '{
  "userId": "me",
  "q": "is:unread",
  "maxResults": 20
}'

​
Modify Labels

gws gmail users messages modify \
  --params '{"userId": "me", "id": "18d1e2f3a4b5c6d7"}' \
  --json '{
    "addLabelIds": ["IMPORTANT"],
    "removeLabelIds": ["UNREAD"]
  }'

​
Create Draft

echo -e "To: recipient@example.com\nSubject: Draft\n\nDraft content" | \
  base64 | \
  gws gmail users drafts create \
    --params '{"userId": "me"}' \
    --json '{"message": {"raw": "<base64-encoded-message>"}}'

​
List Labels

gws gmail users labels list --params '{"userId": "me"}'

​
Response Format

Message list response: 
{
  "messages": [
    {
      "id": "18d1e2f3a4b5c6d7",
      "threadId": "18d1e2f3a4b5c6d7"
    }
  ],
  "nextPageToken": "xyz789...",
  "resultSizeEstimate": 42
}
Full message response: 
{
  "id": "18d1e2f3a4b5c6d7",
  "threadId": "18d1e2f3a4b5c6d7",
  "labelIds": ["INBOX", "UNREAD"],
  "snippet": "Hello, this is a preview of the email...",
  "payload": {
    "headers": [
      {"name": "From", "value": "sender@example.com"},
      {"name": "Subject", "value": "Important Update"}
    ],
    "body": {"data": "SGVsbG8gd29ybGQ="}
  }
}
  • +send - Send an email message
  • +triage - Show unread inbox summary
  • +watch - Watch for new emails and stream as NDJSON

​
Key Resources

  • users.messages - Send, read, manage messages
  • users.drafts - Create and manage drafts
  • users.labels - Create and manage labels
  • users.threads - Manage email threads
  • users.settings - Manage Gmail settings
  • users.history - Track mailbox changes

​
Learn More

​
Schema Inspection

Before calling any method, inspect its schema: 
gws schema gmail.users.messages.list
gws schema gmail.users.messages.send