| 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
- Authenticate — obtain or refresh the OAuth2 token:
headers = {"Authorization": f"Bearer {access_token}"}
- 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", [])
- Parse each message — extract sender, subject, body, labels, and attachment metadata
- Store locally — persist parsed data under
$COGNITHOR_HOME/data/gmail/ as JSON
- 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
