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:

   headers = {"Authorization": f"Bearer {access_token}"}

2. Fetch new messages since the last sync timestamp:

   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