Gmail Email Management

This skill provides comprehensive guidance for managing Gmail emails, labels, and organization.

Requirements

• Hyper MCP installed and connected. https://app.hyperfx.ai/mcp
• Gmail integration enabled at https://app.hyperfx.ai/apps.

Label Operations - Critical Distinctions

ADD LABEL (keeps email in current location + adds new label)

• Use: gmaillabelsadd
• Use case: Adding labels WITHOUT moving the email from its current location
• Example: Email stays in INBOX and also gets labeled "Important"

MOVE TO LABEL (removes from INBOX + adds to target label)

• Use: gmailmessagesmovetolabel
• Use case: Moving email OUT of inbox and INTO a specific label/folder
• Example: Email is removed from INBOX and moved to "Archive" or "Work"
• This performs TWO operations: removes INBOX label + adds target label

REMOVE LABEL (removes specific label)

• Use: gmaillabelsremove
• Use case: Removing labels from an email
• Can remove any label including INBOX

Getting Label IDs

CRITICAL: Most Gmail label operations require label IDs, NOT label names.

• Always call gmaillabelslist first to get available labels and their IDs
• Label IDs look like: "Label123", "Label456", or system labels: "INBOX", "SENT", "TRASH"
• Never guess or make up label IDs

Common Workflows

Email Triage/Organization

1. Call gmaillabelslist to see available labels
2. Call gmailmessageslist to get emails
3. Use gmailmessagesmovetolabel to move emails from INBOX to appropriate labels

Adding Categories (keep in inbox)

1. Call gmaillabelslist to get label IDs
2. Use gmaillabelsadd to categorize emails while keeping them in INBOX

Creating New Labels

• Use gmaillabelscreate if the desired label doesn't exist
• Returns the new label's ID for immediate use

Searching and Listing Messages

gmailmessageslist supports full Gmail search query syntax:

• query parameter accepts the same syntax as Gmail's search box
• Examples: "is:unread", "from:[email protected]", "has:attachment subject:invoice"
• Combine operators: "from:[email protected] is:unread has:attachment"
• By default, excludes drafts (adds -in:draft automatically)
• Use label parameter to filter by specific label

Drafts Workflow

Creating and sending draft emails

1. gmaildraftscreate - Create initial draft
2. gmaildraftsupdate - Edit existing draft (optional)
3. gmaildraftssend - Send the draft as email

Managing drafts

• gmaildraftslist - List all draft emails
• gmaildraftsget - Get a specific draft by ID
• gmaildraftsdelete - Delete a draft without sending

When to use drafts vs direct send

• Use gmailmessagessend for immediate one-step sending
• Use draft workflow when you want to review/edit before sending or schedule for later

Email Actions - Important Distinctions

Archive vs Trash

• gmailmessagesarchive - Removes from INBOX but keeps in "All Mail" (recoverable, not deleted)
• gmailmessagestrash - Moves to Trash folder (will be auto-deleted after 30 days)
• Archive is the preferred way to "clean up" inbox while keeping emails

Attachments

• gmailattachmentsget - Download attachments from received emails
• When sending emails with attachments, use file_ids parameter (requires files to be in the database first)

Tool Selection Quick Reference