Skills
skills/vm0-ai/vm0-skills/gmail

gmail

Installation
SKILL.md

Gmail API

Read, send, and manage emails via Google's Gmail REST API.

Official docs: https://developers.google.com/workspace/gmail/api/reference/rest

When to Use

Use this skill when you need to:

  • Read and search emails
  • Send emails or reply to threads
  • Manage drafts
  • Create and manage labels
  • List and modify threads
  • Get user profile information

Placeholders: Values in {curly-braces} like {message-id} are placeholders. Replace them with actual values when executing.

User Profile

Get Profile

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/profile" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Messages

List Messages

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?maxResults=10" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

List Messages with Query

Search using Gmail query syntax:

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages?q=is:unread&maxResults=10" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Common queries:

  • is:unread - Unread messages
  • from:example@gmail.com - From specific sender
  • subject:hello - Subject contains "hello"
  • after:2024/01/01 - After date
  • has:attachment - Has attachments
  • label:INBOX - In inbox

Get Message

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Get Message (Metadata Only)

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}?format=metadata&metadataHeaders=From&metadataHeaders=Subject&metadataHeaders=Date" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Send Email

# Encode subject using RFC 2047 MIME encoding for non-ASCII characters
ENCODED_SUBJECT="=?UTF-8?B?$(printf '%s' "{subject}" | base64 -w 0)?="

# Create RFC 2822 message and base64url encode
RAW_MESSAGE=$(printf "To: {recipient-email}\r\nSubject: ${ENCODED_SUBJECT}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n{body-text}" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

Write to /tmp/gmail_request.json:

{
  "raw": "$RAW_MESSAGE"
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Reply to Thread

# Encode subject using RFC 2047 MIME encoding for non-ASCII characters
ENCODED_SUBJECT="=?UTF-8?B?$(printf '%s' "Re: {original-subject}" | base64 -w 0)?="

# Include In-Reply-To and References headers for proper threading
RAW_MESSAGE=$(printf "To: {recipient-email}\r\nSubject: ${ENCODED_SUBJECT}\r\nIn-Reply-To: <{original-message-id}>\r\nReferences: <{original-message-id}>\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n{reply-text}" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

Write to /tmp/gmail_request.json:

{
  "raw": "$RAW_MESSAGE",
  "threadId": "{thread-id}"
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/send" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Modify Message Labels

Write to /tmp/gmail_request.json:

{
  "addLabelIds": ["STARRED"],
  "removeLabelIds": ["UNREAD"]
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}/modify" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Trash Message

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}/trash" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Delete Message Permanently

curl -s -X DELETE "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Threads

List Threads

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/threads?maxResults=10" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Get Thread

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/threads/{thread-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Trash Thread

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/threads/{thread-id}/trash" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Labels

List Labels

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/labels" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" | jq '.labels[] | {id, name, type}'

Create Label

Write to /tmp/gmail_request.json:

{
  "name": "{label-name}",
  "labelListVisibility": "labelShow",
  "messageListVisibility": "show"
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/labels" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Delete Label

curl -s -X DELETE "https://gmail.googleapis.com/gmail/v1/users/me/labels/{label-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Drafts

List Drafts

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/drafts" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Create Draft

# Encode subject using RFC 2047 MIME encoding for non-ASCII characters
ENCODED_SUBJECT="=?UTF-8?B?$(printf '%s' "{subject}" | base64 -w 0)?="

RAW_MESSAGE=$(printf "To: {recipient-email}\r\nSubject: ${ENCODED_SUBJECT}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n{body-text}" | base64 -w 0 | tr '+/' '-_' | tr -d '=')

Write to /tmp/gmail_request.json:

{
  "message": {
    "raw": "$RAW_MESSAGE"
  }
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/drafts" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Send Draft

Write to /tmp/gmail_request.json:

{
  "id": "{draft-id}"
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/drafts/send" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Delete Draft

curl -s -X DELETE "https://gmail.googleapis.com/gmail/v1/users/me/drafts/{draft-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Attachments

Get Attachment

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}/attachments/{attachment-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" | jq -r '.data' | base64 -d > attachment.bin

Settings

Get Vacation Settings

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/settings/vacation" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Update Vacation Settings

Write to /tmp/gmail_request.json:

{
  "enableAutoReply": true,
  "responseSubject": "Out of Office",
  "responseBodyPlainText": "I am currently out of office.",
  "restrictToContacts": false,
  "restrictToDomain": false
}

Then run:

curl -s -X PUT "https://gmail.googleapis.com/gmail/v1/users/me/settings/vacation" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

List Filters

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/settings/filters" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)"

Create Filter

Write to /tmp/gmail_request.json:

{
  "criteria": {
    "from": "{filter-email}"
  },
  "action": {
    "addLabelIds": ["TRASH"],
    "removeLabelIds": ["INBOX"]
  }
}

Then run:

curl -s -X POST "https://gmail.googleapis.com/gmail/v1/users/me/settings/filters" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" --header "Content-Type: application/json" -d @/tmp/gmail_request.json

Common Scopes

Scope Permission
gmail.readonly Read-only access
gmail.send Send emails only
gmail.compose Create drafts and send
gmail.modify Read, send, delete, manage
gmail.labels Manage labels only
gmail.settings.basic Manage basic settings
gmail.settings.sharing Manage sensitive settings

Use full URL: https://www.googleapis.com/auth/gmail.modify

Decode Message Body

Gmail returns message body as base64url encoded. To decode:

curl -s "https://gmail.googleapis.com/gmail/v1/users/me/messages/{message-id}" --header "Authorization: Bearer $(printenv GMAIL_TOKEN)" | jq -r '.payload.body.data // .payload.parts[0].body.data' | tr '_-' '/+' | base64 -d

Guidelines

  1. Rate Limits: Gmail API has quota limits; implement exponential backoff
  2. Batch Requests: Use batch endpoints for multiple operations
  3. Message Format: Messages must be RFC 2822 compliant and base64url encoded

API Reference

Weekly Installs
68
Repository
vm0-ai/vm0-skills
GitHub Stars
52
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
gemini-cli58
opencode57
codex56
github-copilot54
amp54
cursor54