Gmail Enhanced

Enhanced Gmail integration with advanced features including label management, attachment handling, advanced search, email parsing, and automated email proces...

Security Scan

The skill appears to implement an enhanced Gmail client and mostly matches that purpose, but the package metadata omits required credentials/dependencies and the package provides code that will read/write OAuth credential files — those mismatches and missing install info are concerning.

Purpose & Capability

The name and description (Gmail features like search, labels, attachments, parsing, automation) align with the code and SKILL.md. The code uses the Gmail API and expects OAuth credentials and tokens, which is appropriate for this purpose.

Instruction Scope

SKILL.md and the code direct the agent to use OAuth credentials, run the local OAuth flow, read credentials.json and tokens.json, download and upload attachments (arbitrary local paths), and save tokens to disk. Those actions are expected for a Gmail client, but they do involve reading/writing local files and handling arbitrary attachments — so users should be aware it needs filesystem access and will store a refresh token locally.

Install Mechanism

There is no install spec despite a non-trivial Python module being included. The code imports google-auth, google_auth_oauthlib, and googleapiclient, but the registry metadata doesn't declare these dependencies or provide installation instructions. Missing dependency/install info is a deployment/operational risk and reduces auditability.

Credentials

Registry metadata lists no required env vars or primary credential, but both SKILL.md and the code expect GMAIL_CREDENTIALS_PATH and GMAIL_TOKEN_PATH (or default files). That mismatch is an incoherence: the skill will require OAuth credential files and will write a token file, yet the package metadata doesn't declare this. The skill will also access arbitrary local files when handling attachments (expected for functionality) — make sure you trust any code that can read local paths you pass to it.

Persistence & Privilege

The skill is not always-enabled and does not request elevated platform privileges. It will create/write its own token file (normal for OAuth clients) but does not appear to modify other skills or global agent settings.

What to consider before installing

This skill implements an OAuth-based Gmail client and will prompt for OAuth credentials, run a local OAuth flow, read your credentials.json and tokens.json (or the paths you set), and write a tokens file (containing refresh tokens) to disk. Before installing: 1) Only proceed if you trust the publisher, because the code will be able to read/write local files and access your Gmail via granted scopes. 2) Be aware the registry metadata does not declare the required env vars or Python dependencies (google-auth, google-auth-oauthlib, google-api-python-client); you will need to install them manually. 3) Review where tokens will be saved (GMAIL_TOKEN_PATH) and whether that location is acceptable. 4) When using attachment features, avoid pointing the skill at sensitive local files and consider scanning attachments before opening. 5) If you want higher assurance, request the publisher add an install spec, declare required env vars, and provide a dependency list and a short security/privacy note describing token storage and telemetry (if any).

Advanced Gmail integration with powerful automation features.

Features

1. Advanced Search

• Complex query building (AND, OR, NOT)
• Date range filters
• Attachment filters
• Label filters
• Search within attachments

2. Label Management

• Create, rename, delete labels
• Nested labels (folders)
• Color customization
• Label statistics

3. Attachment Handling

• Download attachments
• Upload and send attachments
• Filter attachments by type/size
• Extract attachments to cloud storage

4. Email Processing

• Auto-categorize emails
• Extract data from emails
• Auto-reply rules
• Email templates
• Bounce detection

5. Email Parsing

• Extract structured data
• Parse invoices, receipts
• Extract contact info
• HTML parsing

Prerequisites

1. Enable Gmail API in Google Cloud Console
2. Create OAuth 2.0 credentials
3. Download credentials.json
4. Generate tokens.json (run once with authentication)

Configuration

export GMAIL_CREDENTIALS_PATH="/path/to/credentials.json"
export GMAIL_TOKEN_PATH="/path/to/tokens.json"

Or place credentials in default locations:

• ~/.credentials/gmail-credentials.json
• ~/.credentials/gmail-token.json

Usage

Send Email

from gmail_enhanced import GmailClient

gmail = GmailClient()

# Simple email
gmail.send(
    to="[e-mail]",
    subject="Hello",
    body="Email content"
)

# With attachment
gmail.send(
    to="[e-mail]",
    subject="Report",
    body="Please find the report attached",
    attachments=["report.pdf"]
)

Advanced Search

# Complex queries
results = gmail.search(
    query="from:[e-mail]",
    label="INBOX",
    after="2024/01/01",
    has_attachments=True
)

# Search with OR
results = gmail.search_or([
    "subject:urgent",
    "label:important"
])

Label Management

# Create label
label = gmail.create_label("Projects/Work/Q1", color="#4A90E2")

# Get label stats
stats = gmail.get_label_stats("INBOX")

# Apply labels
gmail.add_labels(["Label1", "Label2"], message_ids)

Attachment Handling

# Download attachments from search results
attachments = gmail.search_attachments(
    query="subject:invoice",
    save_dir="./downloads"
)

# Upload attachment
gmail.send(
    to="[e-mail]",
    subject="File",
    attachments=["/path/to/file.pdf"]
)

Auto-categorization

# Create rule
gmail.add_rule(
    name="Categorize invoices",
    query="subject:invoice has:attachment",
    add_labels=["Processed/Invoices"]
)

# Run rules
gmail.process_rules()

API Reference

Core Methods

Method	Description
send(to, subject, body, attachments, cc, bcc)	Send email
search(query, max_results, label)	Search emails
get_message(msg_id, format)	Get email details
delete_message(msg_id)	Move to trash
archive_message(msg_id)	Archive email

Label Methods

Method	Description
create_label(name, color)	Create label
rename_label(old_name, new_name)	Rename label
delete_label(name)	Delete label
get_labels()	List all labels
get_label_stats(label)	Get label statistics

Attachment Methods

Method	Description
download_attachment(msg_id, attachment_id, save_path)	Download attachment
search_attachments(query, save_dir)	Search and download
get_attachment_info(msg_id)	List attachments

Automation Methods

Method	Description
add_rule(name, query, actions)	Create processing rule
process_rules()	Run all rules
create_template(name, subject, body)	Create email template
send_template(template_name, to, variables)	Send using template

Parsing Methods

Method	Description
parse_email(msg_id)	Extract structured data
extract_invoice(msg_id)	Parse invoice data
extract_contacts(msg_id)	Extract email addresses

Email Query Syntax

Basic:
  from:[e-mail]
  to:[e-mail]
  subject:keyword
  "exact phrase"

Filters:
  after:2024/01/01
  before:2024/12/31
  older_than:7d
  newer_than:2h

Flags:
  has:attachment
  has:drive
  is:unread
  is:starred
  is:important

Labels:
  label:INBOX
  label:Work

Combinations:
  from:boss AND subject:urgent
  (from:alice OR from:bob) AND is:unread

Error Handling

Common errors:

• invalid_credentials: Re-authenticate
• rate_limit: Wait and retry
• not_found: Message ID invalid
• permission_denied: Check scopes

Scopes Required

https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.labels
https://www.googleapis.com/auth/gmail.modify

Links

• Gmail API Documentation
• Google Cloud Console
• OAuth Setup Guide