home / skills / abdullahbeam / nexus-design-abdullah / gmail

gmail skill

safe

This skill helps you manage Gmail by reading, composing drafts, and organizing messages with safe, draft-first workflows.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill gmail

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

4.9 KB

---
name: gmail
version: 1.3
description: "Read, send, and manage Gmail emails. Load when user mentions 'gmail', 'email', 'send email', 'check email', 'inbox', 'draft', or references sending/reading emails."
---

## Purpose

Automate Gmail operations including reading, sending, replying, forwarding, and managing emails. Useful for email automation, inbox management, and communication workflows.

# Gmail

Read, send, and manage Gmail via OAuth authentication.

---

## CRITICAL SAFETY RULES

**These rules are MANDATORY and must NEVER be bypassed:**

### 1. NEVER Send Without Explicit Approval
- **ALWAYS** show the user the complete email (to, subject, body) before sending
- **ALWAYS** ask for explicit confirmation: "Do you want me to send this email? (yes/no)"
- **NEVER** auto-send emails, even if user says "send an email to X"
- **NEVER** send multiple emails in a loop without per-email confirmation

### 2. Draft-First Workflow (DEFAULT BEHAVIOR)
- **ALL send/reply/forward operations create a draft FIRST**
- User sees the draft and chooses: `yes` (send now), `no` (delete draft), or `keep-draft` (review in Gmail)
- This ensures user can ALWAYS review in Gmail UI before any email is sent

### 3. Sensitive Operations Require Confirmation
| Operation | Requires Confirmation |
|-----------|----------------------|
| Send email | **YES - ALWAYS** |
| Reply to email | **YES - ALWAYS** |
| Forward email | **YES - ALWAYS** |
| Send draft | **YES - ALWAYS** |
| Delete draft | Yes |
| Trash email | Yes |

### 4. Read Operations Are Safe
These do NOT require confirmation:
- List emails, Search emails, Read email content
- List labels, List drafts, Get attachment

---

## Pre-Flight Check (ALWAYS RUN FIRST)

```bash
python3 00-system/skills/google/google-master/scripts/google_auth.py --check --service gmail
```

**Exit codes:**
- **0**: Ready to use - proceed with user request
- **1**: Need to login - run `python3 00-system/skills/google/google-master/scripts/google_auth.py --login`
- **2**: Missing credentials or dependencies - see [../google-master/references/setup-guide.md](../google-master/references/setup-guide.md)

---

## Quick Reference

### List Emails
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py list --max 10
```

### List Unread Emails
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py list --query "is:unread" --max 10
```

### Search Emails
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py search "from:[email protected] subject:report"
```

### Read Email
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py read <message_id>
```

### Send Email
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py send --to "[email protected]" --subject "Hello" --body "Message body"
```

### Reply to Email
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py reply <message_id> --body "Reply text"
```

### Forward Email
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py forward <message_id> --to "[email protected]"
```

### Create Draft
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py draft --to "[email protected]" --subject "Draft" --body "Content"
```

### List Drafts
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py drafts
```

### List Labels
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py labels
```

### Trash/Archive/Mark Read
```bash
python3 00-system/skills/google/gmail/scripts/gmail_operations.py trash <message_id>
python3 00-system/skills/google/gmail/scripts/gmail_operations.py archive <message_id>
python3 00-system/skills/google/gmail/scripts/gmail_operations.py mark-read <message_id>
```

---

## Gmail Search Syntax

| Operator | Example | Description |
|----------|---------|-------------|
| `from:` | `from:[email protected]` | Emails from sender |
| `to:` | `to:[email protected]` | Emails to recipient |
| `subject:` | `subject:meeting` | Subject contains word |
| `is:unread` | `is:unread` | Unread emails |
| `has:attachment` | `has:attachment` | Has attachments |
| `after:` | `after:2024/01/01` | After date |
| `before:` | `before:2024/12/31` | Before date |
| `label:` | `label:important` | Has label |

---

## Error Handling

See [../google-master/references/error-handling.md](../google-master/references/error-handling.md) for common errors and solutions.

---

## Setup

First-time setup: [../google-master/references/setup-guide.md](../google-master/references/setup-guide.md)

**Quick start:**
1. `pip install google-auth google-auth-oauthlib google-api-python-client`
2. Create OAuth credentials in Google Cloud Console (enable Gmail API, choose "Desktop app")
3. Add to `.env` file at Nexus root:
   ```
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_PROJECT_ID=your-project-id
   ```
4. Run `python3 00-system/skills/google/google-master/scripts/google_auth.py --login`

Overview

This skill automates Gmail operations so you can read, compose, reply, forward, and manage messages using OAuth authentication. It focuses on safe email workflows by defaulting to draft-first operations and requiring explicit user confirmation before any send or delete action. It also supports searching, listing labels, and basic mailbox actions like archive or trash.

How this skill works

The skill connects to Gmail via OAuth and runs a pre-flight authentication check before any operation. Read-only actions (list, search, read, labels, attachments) execute immediately, while send/reply/forward actions create a draft first and present the full to/subject/body for user approval. Sensitive operations such as sending, trashing, or deleting drafts always require explicit confirmation.

When to use it

When you need to list or search messages across your Gmail account
When you want to compose or reply to email with a safety review step
When you need to create or inspect drafts before sending
When you need to archive, trash, or mark messages as read
When you want to list labels or fetch attachments for processing

Best practices

Run the required pre-flight auth check before use to verify OAuth readiness
Use the draft-first workflow to review content in Gmail before sending
Provide clear recipient, subject, and body details so drafts are accurate for confirmation
Avoid automating bulk sends; confirm each message individually
Keep OAuth credentials secure and follow the setup steps to enable the Gmail API

Example use cases

List the 10 most recent unread emails and open specific message bodies
Search for emails from a sender or by subject and save matching message IDs
Create a draft addressed to a client, review it, then send after confirmation
Reply to or forward a selected message: a draft is created and you confirm send
Archive or trash specific messages after manual confirmation

FAQ

Do send and reply actions send immediately?

No. All send, reply, and forward actions create a draft first. You will be shown the full to/subject/body and asked: "Do you want me to send this email? (yes/no)".

What should I do if authentication fails the pre-flight check?

Run the login step shown by the pre-flight output. If dependencies or credentials are missing, follow the setup guide to create OAuth credentials and install required packages.