Imported from plosson/agentio (
claude/skills/agentio-gmail/SKILL.md). Install upstream withnpx skills add plosson/agentio --skill agentio-gmail. Copyright stays with the author.
Gmail via agentio
Auto-generated from agentio skill gmail. Do not edit by hand.
agentio gmail list
List messages
Options:
--profile <name>: Profile name (optional if only one profile exists)--limit <n>: Number of messages (default: 10)--query <query>: Gmail search query (see "gmail search --help" for syntax)--label <label>: Filter by label (repeatable) (default: )
Examples:
# 10 most recent messages
agentio gmail list
# 25 most recent in the inbox
agentio gmail list --limit 25 --label INBOX
# unread messages from the last week
agentio gmail list --query "is:unread newer_than:7d"
# use a specific profile
agentio gmail list --profile alice@example.com
agentio gmail get
Get a message
Options:
--profile <name>: Profile name (optional if only one profile exists)--format <format>: Body format: text, html, or raw (default: text)--body-only: Output only the message body
Examples:
# full message with headers
agentio gmail get 18c4f1a2b3d
# plain-text body only (good for piping to a file)
agentio gmail get 18c4f1a2b3d --body-only > message.txt
# raw HTML body
agentio gmail get 18c4f1a2b3d --format html --body-only
agentio gmail search
Search messages using Gmail query syntax
Options:
--query <query>: Search query--profile <name>: Profile name (optional if only one profile exists)--limit <n>: Max results (capped at 10000; >100 returns IDs only without per-message metadata) (default: 10)--ids-only: Print one message ID per line (pipe-friendly into archive/label)
Examples:
# unread mail from a specific sender in the last week
agentio gmail search --query "from:alice@example.com is:unread newer_than:7d"
# messages with attachments after a date
agentio gmail search --query "has:attachment after:2024/01/01" --limit 25
# subject keyword in inbox, excluding spam
agentio gmail search --query "subject:invoice label:inbox -label:spam"
# exact phrase across all mail
agentio gmail search --query '"quarterly report"'
# bulk pipe: archive everything matching a query
agentio gmail search --query "from:noreply@example.com older_than:6m" --limit 5000 --ids-only \
| agentio gmail archive
Query syntax: from:, to:, cc:, subject:, label:, is:unread|starred|important,
has:attachment, after:YYYY/MM/DD, before:YYYY/MM/DD, newer_than:7d, older_than:1m.
Combine with spaces (AND), OR, or - to negate.
agentio gmail send
Send an email
Options:
--profile <name>: Profile name (optional if only one profile exists)--to <email>: Recipient (repeatable, required unless --reply-to) (default: )--cc <email>: CC recipient (repeatable) (default: )--bcc <email>: BCC recipient (repeatable) (default: )--subject <subject>: Email subject (required unless --reply-to)--subject-file <path>: Read subject from a UTF-8 file (preferred for agents; avoids shell quoting)--body <body>: Email body (omit or pass "-" to read from stdin)--body-file <path>: Read body from a UTF-8 file (preferred for agents; avoids shell quoting)--spec <path.json>: Compose from JSON file {to,cc,bcc,subject,body,attachments}; flags override--html: Treat body as HTML--reply-to <thread-id>: Thread ID to reply to (derives to/subject from thread)--attachment <path>: File to attach (repeatable) (default: )--inline <cid:path>: Inline image (repeatable, format: contentId:filepath). Supports PNG, JPG, GIF only (not SVG) (default: )
Examples:
# plain-text email
agentio gmail send --to alice@example.com --subject "Hello" --body "Hi Alice!"
# body from stdin (great for piping)
echo "Sent via pipe" | agentio gmail send --to alice@example.com --subject "Note"
# preferred for agents: subject/body from UTF-8 files
agentio gmail send --to alice@example.com --subject-file ./subject.txt --body-file ./body.txt
# reply within an existing thread (to/subject derived from thread)
agentio gmail send --reply-to 18c4f1a2b3d --body "Thanks!"
# HTML body with an attachment and an inline image
agentio gmail send --to alice@example.com --cc bob@example.com \
--subject "Report" --html \
--body '<p>See chart:</p><img src="cid:chart1">' \
--attachment ./report.pdf --inline chart1:./chart.png
agentio gmail draft [draft-id]
Create an email draft (or update an existing one with [draft-id])
Options:
--profile <name>: Profile name (optional if only one profile exists)--to <email>: Recipient (repeatable, required unless --reply-to) (default: )--cc <email>: CC recipient (repeatable) (default: )--bcc <email>: BCC recipient (repeatable) (default: )--subject <subject>: Email subject (required unless --reply-to)--subject-file <path>: Read subject from a UTF-8 file (preferred for agents; avoids shell quoting)--body <body>: Email body (omit or pass "-" to read from stdin)--body-file <path>: Read body from a UTF-8 file (preferred for agents; avoids shell quoting)--spec <path.json>: Compose from JSON file {to,cc,bcc,subject,body,attachments}; flags override--html: Treat body as HTML--reply-to <thread-id>: Thread ID to reply to (derives to/subject from thread)--attachment <path>: File to attach (repeatable) (default: )--inline <cid:path>: Inline image (repeatable, format: contentId:filepath). Supports PNG, JPG, GIF only (not SVG) (default: )
Examples:
# save a draft for later editing in Gmail
agentio gmail draft --to alice@example.com --subject "Hello" --body "Draft body"
# preferred for agents: subject/body from UTF-8 files (avoids shell quoting bugs)
agentio gmail draft --to alice@example.com --subject-file ./subject.txt --body-file ./body.txt
# or a single JSON spec (flags still override individual fields)
agentio gmail draft --spec ./draft.json
# update an existing draft (replaces its entire content)
agentio gmail draft r-1234567890 --to alice@example.com --subject "Hello" --body "Revised body"
# draft a reply within an existing thread
agentio gmail draft --reply-to 18c4f1a2b3d --body "Draft reply"
# draft with attachment, body from stdin
cat message.txt | agentio gmail draft --to alice@example.com \
--subject "Notes" --attachment ./notes.pdf
agentio gmail draft delete <draft-id...>
Delete (discard) one or more drafts
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# discard a draft
agentio gmail draft delete r-1234567890
# discard several at once
agentio gmail draft delete r-123... r-456...
agentio gmail archive [message-id...]
Archive one or more messages (bulk-safe via batchModify)
Options:
--profile <name>: Profile name (optional if only one profile exists)--chunk-size <n>: IDs per batchModify call (max 1000) (default: 1000)--max-retries <n>: Retries per chunk on 429/5xx (default: 5)--dry-run: Print chunk plan without calling the API
Examples:
# archive one message
agentio gmail archive 18c4f1a2b3d
# archive several at once
agentio gmail archive 18c4f1a2b3d 18c4f1a2b3e 18c4f1a2b3f
# archive thousands by piping IDs from search (uses messages.batchModify, 1000/call)
agentio gmail search --query "from:noreply@example.com older_than:1y" --limit 5000 --ids-only \
| agentio gmail archive
# preview the chunk plan without calling the API
echo "id1 id2 id3" | agentio gmail archive --dry-run
agentio gmail mark <message-id...>
Mark one or more messages as read or unread
Options:
--profile <name>: Profile name (optional if only one profile exists)--read: Mark as read--unread: Mark as unread
Examples:
# mark one message as read
agentio gmail mark 18c4f1a2b3d --read
# mark several back to unread
agentio gmail mark 18c4f1a2b3d 18c4f1a2b3e --unread
agentio gmail labels list
List all labels
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# list every label (system + user)
agentio gmail labels list
# list labels for a specific profile
agentio gmail labels list --profile alice@example.com
agentio gmail labels create
Create a new label
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# create a top-level label
agentio gmail labels create receipts
# create a nested label (use "/" for hierarchy)
agentio gmail labels create auto/receipts
# nested two levels deep
agentio gmail labels create work/clients/acme
agentio gmail labels delete
Delete a user label
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# delete a user label by name
agentio gmail labels delete receipts
# delete a nested label
agentio gmail labels delete auto/receipts
# delete by label ID
agentio gmail labels delete Label_1234567890
agentio gmail labels rename
Rename a user label
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# rename a label
agentio gmail labels rename receipts invoices
# move a label into a nested hierarchy
agentio gmail labels rename receipts auto/receipts
agentio gmail filters list
List all filters
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# list every filter
agentio gmail filters list
# list filters for a specific profile
agentio gmail filters list --profile alice@example.com
agentio gmail filters get
Get a filter
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# show full filter details
agentio gmail filters get ANe1BmgABCDEF1234567890
agentio gmail filters create
Create a Gmail filter
Options:
--profile <name>: Profile name (optional if only one profile exists)--from <email>: Match sender--to <email>: Match recipient--subject <text>: Match subject text--query <q>: Gmail search query (same syntax as "gmail search")--negated-query <q>: Gmail search query that must NOT match--has-attachment: Match only messages with attachments--exclude-chats: Exclude chat messages--size <bytes>: Match by message size (paired with --size-comparison)--size-comparison <cmp>: Size comparison: larger|smaller (paired with --size)--apply <label>: Label to apply (name or ID, repeatable) (default: )--remove <label>: Label to remove (name or ID, repeatable) (default: )--forward <email>: Forward to a verified forwarding address
Examples:
# apply a label to mail from a sender
agentio gmail filters create --from noreply@example.com --apply Receipts
# archive newsletters automatically
agentio gmail filters create --from news@example.com --remove INBOX
# complex criteria + multiple actions
agentio gmail filters create \
--query "has:attachment subject:invoice" \
--apply Auto/Invoices --remove INBOX
# forward all mail from a sender (forwarding address must be verified in Gmail settings)
agentio gmail filters create --from boss@example.com --forward archive@me.com
# size-based filter (5MB or larger)
agentio gmail filters create --size 5000000 --size-comparison larger --apply Large
agentio gmail filters delete <id...>
Delete one or more filters
Options:
--profile <name>: Profile name (optional if only one profile exists)
Examples:
# delete one filter
agentio gmail filters delete ANe1BmgABCDEF1234567890
# delete several at once
agentio gmail filters delete ANe1Bmg... ANe1Bmh... ANe1Bmi...
agentio gmail label [id...]
Apply and/or remove labels on messages or threads (bulk-safe via batchModify)
Options:
--profile <name>: Profile name (optional if only one profile exists)--apply <name>: Label to apply (name or ID, repeatable) (default: )--remove <name>: Label to remove (name or ID, repeatable) (default: )--thread: Treat IDs as thread IDs (expands to messages for batching)--chunk-size <n>: IDs per batchModify call (max 1000) (default: 1000)--max-retries <n>: Retries per chunk on 429/5xx (default: 5)--dry-run: Print chunk plan without calling the API
Examples:
# apply a label to one message
agentio gmail label 18c4f1a2b3d --apply receipts
# remove a label from several messages
agentio gmail label 18c4f1a2b3d 18c4f1a2b3e --remove INBOX
# archive (remove INBOX) and apply a label in one call
agentio gmail label 18c4f1a2b3d --apply auto/receipts --remove INBOX
# apply multiple labels to a thread
agentio gmail label 18c4f1a2b3d --thread --apply important --apply work
# bulk: pipe IDs from search and label them
agentio gmail search --query "subject:invoice older_than:1y" --limit 5000 --ids-only \
| agentio gmail label --apply Archive/Invoices --remove INBOX
# preview the chunk plan without calling the API
echo "id1 id2 id3" | agentio gmail label --apply receipts --dry-run
agentio gmail attachment
Download attachments from a message
Options:
--profile <name>: Profile name (optional if only one profile exists)--name <filename>: Download specific attachment by filename (downloads all if not specified)--output <dir>: Output directory (default: .)
Examples:
# download every attachment to the current directory
agentio gmail attachment 18c4f1a2b3d
# download all attachments to a specific folder
agentio gmail attachment 18c4f1a2b3d --output ./downloads
# download just one attachment by filename
agentio gmail attachment 18c4f1a2b3d --name invoice.pdf --output ./downloads
agentio gmail export
Export a message as PDF
Options:
--profile <name>: Profile name (optional if only one profile exists)--output <path>: Output file path (default: message.pdf)
Examples:
# export to default message.pdf in CWD
agentio gmail export 18c4f1a2b3d
# export to a specific path
agentio gmail export 18c4f1a2b3d --output ./archive/invoice.pdf
Requires Chrome, Chromium, or Microsoft Edge installed locally.