gmail
Manage Gmail end-to-end — send, reply, search, drafts, labels, attachments, and inbox organization. Use when the user wants to send or reply to email, clean up an inbox, build label systems, manage drafts, or pull attachments.
How do I install this agent skill?
npx skills add https://github.com/hyperfx-ai/marketing-skills --skill gmailIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill facilitates comprehensive Gmail management. It is considered low risk because it handles external email content that could contain instructions designed to manipulate the agent's behavior (indirect prompt injection).
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
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.
How to run the tools in this skill
Every tool in this skill is named by its canonical tool name. Run it with the call your surface gives you:
| Surface | Find a tool | Run it |
|---|---|---|
| Hyper chat | Call the tool by its name; search_tools(queries=["<provider> <action>"]) shows its parameters | <name>(...) |
| MCP client (Claude, Cursor, Codex, ChatGPT) | search("<what you want to do>"), then describe("<name>") | call_read("<name>", {...}), call_write or call_destructive: the one that describe names in call_with |
| Hyper CLI | hyperai search "<what you want to do>", then hyperai describe <name> | hyperai call <name> --json '{...}' |
If a tool is not found: in Hyper chat, find its toolkit id with discover_toolkits and pass it to enable_toolkit. On an MCP client or the CLI, tell the user which integration to connect in Hyper.
Label Operations - Critical Distinctions
ADD LABEL (keeps email in current location + adds new label)
- Use:
gmail_labels_add - 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:
gmail_messages_move_to_label - 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:
gmail_labels_remove - 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
gmail_labels_listfirst to get available labels and their IDs - Label IDs look like: "Label_123", "Label_456", or system labels: "INBOX", "SENT", "TRASH"
- Never guess or make up label IDs
Common Workflows
Email Triage/Organization
- Call
gmail_labels_listto see available labels - Call
gmail_messages_listto get emails - Use
gmail_messages_move_to_labelto move emails from INBOX to appropriate labels
Adding Categories (keep in inbox)
- Call
gmail_labels_listto get label IDs - Use
gmail_labels_addto categorize emails while keeping them in INBOX
Creating New Labels
- Use
gmail_labels_createif the desired label doesn't exist - Returns the new label's ID for immediate use
Searching and Listing Messages
gmail_messages_list supports full Gmail search query syntax:
queryparameter accepts the same syntax as Gmail's search box- Examples:
"is:unread","from:user@example.com","has:attachment subject:invoice" - Combine operators:
"from:user@example.com is:unread has:attachment" - With no
query, the tool adds-in:draft. When you pass aquery, add-in:draftto it yourself - The
labelparameter takes the label NAME (or INBOX, SENT, SPAM, TRASH, CATEGORY_*), not aLabel_…ID. An ID is ignored with no error
Drafts Workflow
Creating and sending draft emails
gmail_drafts_create- Create initial draftgmail_drafts_update- Edit existing draft (optional)gmail_drafts_send- Send the draft as email
Managing drafts
gmail_drafts_list- List all draft emailsgmail_drafts_get- Get a specific draft by IDgmail_drafts_delete- Delete a draft without sending
When to use drafts vs direct send
- Use
gmail_messages_sendfor immediate one-step sending - Use the draft workflow when a person must review or edit the email before it is sent
- To send later, pass
scheduled_at="<ISO datetime>"togmail_messages_send; a draft does not schedule
Replies
gmail_messages_reply(message_id=..., body=..., reply_all=False)sends a reply at oncegmail_drafts_create(reply_to_message_id=..., mode="reply", body=...)drafts a reply;modeis also"reply_all", or"forward"withto
Email Actions - Important Distinctions
Archive vs Trash
gmail_messages_archive- Removes from INBOX but keeps in "All Mail" (recoverable, not deleted)gmail_messages_trash- Moves to Trash folder (will be auto-deleted after 30 days)- Archive is the preferred way to "clean up" inbox while keeping emails
Attachments
gmail_attachments_get- Download attachments from received emails- To attach files, pass their workspace file IDs in
file_ids, not/files/...paths (files_createreturns thefile_id). An unknown ID is skipped with no error, so check each ID before you send
Tool Selection Quick Reference
| Action | Tool |
|---|---|
| Add label X | gmail_labels_add |
| Move to label X | gmail_messages_move_to_label |
| Remove from inbox | gmail_messages_move_to_label (move to target) OR gmail_labels_remove (just remove INBOX) |
| Archive email | gmail_messages_archive (preferred for cleanup) |
| Delete/trash email | gmail_messages_trash |
| Send email now | gmail_messages_send |
| Send email later | gmail_messages_send with scheduled_at="<ISO datetime>" |
| Reply now | gmail_messages_reply |
| Draft a reply or forward | gmail_drafts_create with reply_to_message_id |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/hyperfx-ai/marketing-skills/gmail">View gmail on skillZs</a>