Skip to content
Skills Library
Personal productivity · Tool integration

gmail-sync

/gmail-sync

API integration skill that fetches Gmail messages, syncs inbox labels, and processes attachments via the Gmail REST API. Use when fetching new emails, syncing inbox state, triaging unread messages, exporting mail data, or integrating Gmail into automated workflows.

Repository
cognithor ↗
Licence
Apache-2.0
Last repository change
19.05.2026

Assessment and security

95/ 100Class: good
Format20 / 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
5
Scripts
3
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What to check before installing
  • 3 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: __init__.py, skill.py, test_skill.py

What it does and when to use it

API integration skill that fetches Gmail messages, syncs inbox labels, and processes attachments via the Gmail REST API. Use when fetching new emails, syncing inbox state, triaging unread messages, exporting mail data, or integrating Gmail into automated workflows.

Original author description

API integration skill that fetches Gmail messages, syncs inbox labels, and processes attachments via the Gmail REST API. Use when fetching new emails, syncing inbox state, triaging unread messages, exporting mail data, or integrating Gmail into automated workflows.

How it works

  1. Steps
  2. Example
  3. Error Handling
Original SKILL.md headings · 40 lines, 182 words
SKILL.md preview
---
name: gmail-sync
description: "API integration skill that fetches Gmail messages, syncs inbox labels, and processes attachments via the Gmail REST API. Use when fetching new emails, syncing inbox state, triaging unread messages, exporting mail data, or integrating Gmail into automated workflows."
---

# Gmail Sync

Fetches Gmail messages, syncs labels, and processes attachments via the Gmail REST API using `httpx`. Requires network access.

## Steps

1. **Authenticate** — obtain or refresh the OAuth2 token:
   ```python
   headers = {"Authorization": f"Bearer {access_token}"}
   ```
2. **Fetch new messages** since the last sync timestamp:
   ```python
   async with httpx.AsyncClient() as client:
       resp = await client.get(
           f"{API_BASE}/messages",
           headers=headers,
           params={"q": "after:{last_sync_epoch}"}
       )
       messages = resp.json().get("messages", [])
   ```
3. **Parse each message** — extract sender, subject, body, labels, and attachment metadata
4. **Store locally** — persist parsed data under `$COGNITHOR_HOME/data/gmail/` as JSON
5. **Return summary** — the skill returns `{"data": <parsed_response>}` with message counts

## Example

```
User > Synchronisiere meine Gmail-Inbox
Cognithor > 14 neue Nachrichten synchronisiert (3 ungelesen, 2 mit Anhängen)
         Letzte Synchronisation: 2026-04-20 14:00 UTC
```

## Error Handling

- **401 Unauthorized**: Token expired — trigger OAuth refresh flow before retrying
- **429 Rate Limited**: Back off exponentially (1s, 2s, 4s) up to 3 retries
- **Network timeout**: Log the failure, preserve last-known state, report to user
- **Empty response**: Confirm query parameters are correct; check `last_sync_epoch` is valid
Files in this package (5)
  • SKILL.md 2 KB
  • __init__.py 1 KB
  • manifest.json 1 KB
  • skill.py 1 KB
  • test_skill.py 1 KB

Versions

The database has no other skills named gmail-sync.

Database snapshot: 13.11.2026 · package version 6ece7a847eb7 (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

  • 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 /…
  • 100email-whiz
    Gmail copilot via MCP. Triage, inbox-zero, filters, analytics, labels, cleanup. Use when managing email or automating Gmail. NOT for composing emails, calendar, or non-Gmail.
  • 100gmail
    This skill should be used when searching, fetching, or downloading emails from Gmail. Use for queries like "search Gmail for...", "find emails from John", "show unread emails", "emails about project X", or "download attachment from email".
  • 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.
  • 95gmail-triage
    Review a bounded Gmail inbox or search result, identify actionable messages, and apply explicitly requested organization. Use for mail triage and labeling; summarizing mail does not authorize sending, deleting, or changing inbox settings.
  • 100gmail
    Lists, searches, reads, and sends Gmail messages and labels via native gmail_* tools. Use for inbox triage, unread filters, full message bodies, and outbound email.

Feedback and reports

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