Skip to content
Skills Library
Documents & office · Tool integration

agentio-gmail

/agentio-gmail

Use when interacting with Gmail via the agentio CLI - list, read, search, send, draft, reply, archive, mark, attachments, export.

Repository
agentio ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when interacting with Gmail via the agentio CLI - list, read, search, send, draft, reply, archive, mark, attachments, export.

Original author description

Use when interacting with Gmail via the agentio CLI - list, read, search, send, draft, reply, archive, mark, attachments, export.

How it works

  1. agentio gmail list
  2. agentio gmail get <message-id>
  3. agentio gmail search
  4. agentio gmail send
  5. agentio gmail draft [draft-id]
  6. agentio gmail draft delete <draft-id...>
  7. agentio gmail archive [message-id...]
  8. agentio gmail mark <message-id...>
  9. agentio gmail labels list
  10. agentio gmail labels create <name>
Original SKILL.md headings · 493 lines, 2,007 words
SKILL.md preview
---
name: agentio-gmail
description: Use when interacting with Gmail via the agentio CLI - list, read, search, send, draft, reply, archive, mark, attachments, export.
---

# 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 <message-id>

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 <name>

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 <name-or-id>

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 <old> <new>

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 <id>

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 <message-id>

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 <message-id>

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.
```

Versions

The database has no other skills named agentio-gmail.

Database snapshot: 13.11.2026 · package version 9ceee837c0cd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100agentio-gchat
    Use when interacting with Google Chat via the agentio CLI - send messages, list spaces, read history.
  • 100agentio-gdrive
    Use when interacting with Google Drive via the agentio CLI - list, search, download, upload, folder navigation.
  • 100gmail
    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.
  • 100gmail
    Interact with Gmail - search emails, read messages, send emails, create drafts, and manage labels. Use when user asks to: search email, read email, send email, create email draft, mark as read, archive email, star email, or manage Gmail labels. Lightweight alternative to full…
  • 95google-gmail
    Read, search, triage, label, archive and send Gmail mail / threads / labels / attachments via the Gmail v1 REST API. Use when the user mentions Gmail, "my inbox", unread mail, recent emails from someone, summarising a thread, downloading an attachment, finding mail by label /…
  • 90gws-gmail
    Google Gmail CLI operations via gws. Use when users need to list emails, read messages, send email, manage labels, drafts, attachments, batch operations, or trash messages. Triggers: gmail, email, inbox, send email, mail, labels, archive, trash, drafts, attachments.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.