version: "1.0.1" 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}"} ``

1. 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", []) ``

1. Parse each message — extract sender, subject, body, labels, and attachment metadata
2. Store locally — persist parsed data under $COGNITHOR_HOME/data/gmail/ as JSON
3. 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