← Search

Gmail Connector
Development 🧪 Install ran in our test sandbox · Nov 18, 2026 📌 Pinned version: commit f3656c6
Install test only, on the date shown. This does not guarantee the code is safe.
⚙ Needs: a Caffeine AI project (backend Motoko canister)…

Gmail Connector

Send email as the signed-in user's own Gmail account via OAuth

At a glance
What
Send email as the signed-in user's own Gmail account via OAuth
Cost
Free
Needs
a Caffeine AI project (backend Motoko canister); a Google Cloud project with an OAuth 2.0 Web-application client (client ID + secret, entered in the app's admin settings — never pasted into the chat); the googlemail-client, google-oauth and caffeineai-authorization mops packages; and the extension-authorization skill, which this skill names as a prerequisite for all builds (it provides the signed-in caller every Gmail endpoint requires).
Install
Copy the installer prompt below into your Muse — your agent does the rest.

Version: 0.2.10

Quick answer

Gmail Connector is a free Muse skill that sends email as the signed-in user's own Gmail account via OAuth, as the mandatory recipe for Caffeine AI apps. Each end-user authorizes the canister independently via an OAuth 2.0 Authorization Code flow with PKCE, and tokens are stored per user.

⌁

Install

Copy the install package below, then paste it into Muse🧪 Install ran in our test sandbox · Nov 18, 2026📌 Pinned version: commit f3656c6

Step 0 — before installing anything: read this install prompt, summarize in a few lines what this build does and what installing it involves, then ask me to confirm before you proceed. Prerequisites: a Caffeine AI project (backend Motoko canister); a Google Cloud project with an OAuth 2.0 Web-application client (client ID + secret, entered in the app's admin settings — never pasted into the chat); the googlemail-client, google-oauth and caffeineai-authorization mops packages; and the extension-authorization skill, which this skill names as a prerequisite for all builds (it provides the signed-in caller every Gmail endpoint requires). Install "Gmail Connector" for me. It gives my Caffeine AI build @caffeinelabs's mandatory recipe (version 0.2.10) for sending email as the signed-in user's own Gmail account — distinct from the platform email extensions, which send transactional mail from the app. The only supported path is the googlemail-client mops package (generated Gmail REST API bindings) combined with google-oauth (token exchange, refresh, PKCE): hand-rolled HTTP calls to Google endpoints are explicitly forbidden. Each end-user authorizes the canister independently via an OAuth 2.0 Authorization Code flow with PKCE; access and refresh tokens are stored per-user, keyed by caller, in the canister only, and the 1-hour token is silently refreshed and retried once on 401. The recipe covers the canonical backend layout (main actor, gmail-config and gmail-messaging mixins, LibGmail glue), the admin settings page at /settings/gmail with its copyable /connect/gmail callback URI, the per-user connect and callback page, the minimal scopes (openid email plus gmail.send for a send-only app), and the traps to avoid — above all is_replicated = ?false on every Gmail call. Repository: https://raw.githubusercontent.com/caffeinelabs/skills/f3656c69d957a43a920fc21d9c3a6ef0c74dca21/skills/connector-googlemail/SKILL.md (the skill is the skills/connector-googlemail/ folder at that commit, which contains SKILL.md only) Pinned version: install the code at commit f3656c69d957a43a920fc21d9c3a6ef0c74dca21 exactly (Skill Harbor tested this version). Do not substitute a newer version. If this commit is unreachable, stop and tell me. [FINGERPRINTS] Files at the pinned commit, from Skill Harbor's review of 2026-10-20: - SKILL.md: SHA-256 dd74fd1b9980a219162a2d2f5a860992c41e659d02dd251e0d0b37e4415fb427, 43,047 bytes, 42,869 characters If any of these does not match, it changed since the review: do not install it yet, tell me what you found and let me decide. Updated October 20, 2026: Skill Harbor regenerated this install prompt from the current upstream file, at version 0.2.10 (the previous prompt described version 0.2.9; SKILL.md went from 42,636 to 42,869 characters). Only one line of Motoko code changed, in LibGmail.sendEmail, plus its documentation: a Gmail send failure other than 401 now propagates to the caller as a catchable reject (throw e — the caller can wrap the send in a try/catch and decide whether the surrounding operation continues) instead of trapping the calling message (Runtime.trap), which no caller could catch and which ended the whole message. A failed token refresh still traps in accessTokenOf and remains uncatchable, before as now — surface "re-connect your account" for it. The 401 flow is unchanged: on 401 or Unauthorized the token is silently refreshed, the refreshed token is persisted per-user, and the send is retried once. There is no other change of surface: no change to endpoints, OAuth scopes, data sent, secrets or capabilities, and the propagated error contains neither the token nor the client secret. What is sent, and when: nothing is sent anywhere and nothing is executed during installation itself — installing only downloads the pinned SKILL.md from GitHub and copies it. Sending starts later, when a build built from this recipe is used: the canister sends the user's email through the Gmail API with that user's own bearer, over non-replicated HTTP outcalls, as described in the safety check below. 1. Fetch the SKILL.md file at the pinned commit into a temporary folder, then compare it with the fingerprint from Skill Harbor's review of 2026-10-20 (see [FINGERPRINTS] above). If it does not match, do not install it yet, tell me what you found and let me decide. 2. Safety check: read SKILL.md and review it for anything suspicious (unexpected network calls, shell commands, credential harvesting); STOP on any red flag and tell me. Tell me in plain words what the skill does when used, which services it connects to, whether it reads or sends any personal information or keys, and anything that seems unusual. Confirm these points from the files: - The skill is a single SKILL.md file: instructions and a Motoko recipe — it ships no bundled scripts and no background service, and nothing runs on its own. Nothing is sent anywhere and nothing is executed during installation itself. Everything below happens in use, when a Caffeine build follows the recipe. - Per-user OAuth and token storage, in use: every end-user authorizes the canister independently via the OAuth 2.0 Authorization Code flow with PKCE (code_verifier and code_challenge from google-oauth). Access and refresh tokens are stored per-user in a Map keyed by caller (Principal), plus one pending flow per caller holding the verifier, the exact redirect URI and a random state nonce, consumed when the callback completes. The bearer never leaves the canister: the frontend only ever learns whether the caller has connected (a Bool) and the connected email address — no endpoint returns the token, the refresh token or the full connection, and the frontend never persists tokens (no localStorage, no IndexedDB, no cookies). - Admin configuration: the Google Cloud Web-application client ID and secret are entered through the app's admin settings page (/settings/gmail) and held by the canister only — the secret is used for the token exchange and is never returned to the frontend. The credential setter is gated on the #admin role, and every Gmail endpoint is gated on a signed-in, non-anonymous caller (extension-authorization provides that login flow). The settings page must display the literal, copyable callback URI — window.location.origin + "/connect/gmail" — and the administrator registers that exact value, for every deployed origin, as an authorized redirect URI in Google Cloud Console. - Scopes and the supported path: the recipe's SCOPES are "openid email https://www.googleapis.com/auth/gmail.send" for a send-only app — the connected address is learned via OIDC userinfo (OAuth.getUserEmail, needing only openid email), not via getProfile; add gmail.readonly only when the app actually reads mail. Hand-rolling ic.http_request calls to oauth2.googleapis.com or gmail.googleapis.com is a forbidden anti-pattern: the googlemail-client and google-oauth mops packages are the only supported path. Every Gmail call carries is_replicated = ?false (a replicated outcall would leak the bearer from every node, cost about 13x the cycles, and fail consensus on non-deterministic responses); since 0.2.0 defaultConfig already ships that default. - Send and failure behaviour in this version: on HTTP 401 the canister silently refreshes the token via google-oauth, persists the new token (Google refresh tokens do not rotate, so the original refresh token is kept), and retries the send once. Any other failure of the first send now propagates to the caller as a catchable reject (throw e, preserving the original Gmail error) instead of trapping the calling message, so a caller that must survive a failed send can catch it with a try/catch; if nobody catches it, the call fails with that original error. A failed refresh still traps in accessTokenOf and cannot be caught by any caller. A 429 is surfaced to the caller and is never silently retried (a retry may deliver duplicates). The propagated error contains neither the token nor the client secret. - Frontend requirements in the recipe: an admin-reachable /settings/gmail page with the credentials panel, the copyable redirect URI field and a configured/not-configured status that never displays the credentials; a real /connect/gmail route that catches Google's callback (it must wait for the authenticated actor to be ready before calling completeGmailOAuth once, then clear the OAuth parameters from the URL); and empty-state nudges to connect Gmail where mail is sent. In a combined Gmail + Calendar app the two connectors share one /settings/google page and one /connect/google route, one Client ID/Secret and one connection — never two separate OAuth flows. 3. When I say "yes, install", install it as a skill: copy the fetched SKILL.md into the agent's skills directory, in a folder named "caffeinelabs-connector-googlemail". 4. Verify with no network calls: frontmatter valid, files in place, and the copied SKILL.md still matches its fingerprint above. 5. Report what was installed, where, and what I still need to do myself (e.g. create the Google Cloud Web-application OAuth client and enable the Gmail API, register the app's /connect/gmail callback URI as an authorized redirect for every deployed origin, enter the client ID and secret through the app's admin settings page, add the three mops packages to my Caffeine project, and have each user connect their own Gmail account — no Gmail call happens until a build follows the recipe). GitHub is optional: if I have a GitHub account or the gh CLI, you may use it; otherwise public access is fine. Never require it unless it's in the prerequisites above. Rules: don't touch anything outside the temp folder and the install target. Never ask me to paste secrets in chat — credentials go through the secure vault or environment variables. If anything looks off, stop and ask me.

🔒 Security, provenance and what this touches
🧭 What this touches
Based on the install prompt we scanned, this skill does not run commands, make third-party network calls, install packages, write files, or ask for API keys.
Install prompt analysis · 2026-10-13
🔒 Security and provenance
📌 Pinned version: commit f3656c6 · 2026-10-20
🧪 Install ran in our test sandbox · Nov 18, 2026
👁 Observed during the install test · Nov 18, 2026 : registry.npmjs.org
🔎 Last checked · Nov 19, 2026 : no change detected in the files linked by this install prompt
Skill Harbor never reviews the code of a listed skill. These are dated facts about the install prompt and our install test, not a safety certification. Review a skill yourself before you install it. How we verify
Wanna be extra careful?

The install prompt below already includes the vetting steps: your agent follows the community checklist before installing anything with executable code. Want more?

How to check a skill before installing →

✓

Verification certificate

Dated facts about what was checked for this listing, and how. This is not a safety certification.

Pinned version
f3656c6 · 2026-10-20
Sandbox install test
Install ran in our test sandbox · Nov 18, 2026 · Observed during the install test: registry.npmjs.org
Creator identity
Not verified
Fingerprint watch
Last checked · Nov 19, 2026 : no change detected in the files linked by this install prompt
Install prompt analysis
2026-10-13 : No commands, network calls, packages, file writes or API keys detected.

Skill Harbor never reviews the code of a listed skill. These are dated facts about the install prompt and our install test, not a safety certification. Review a skill yourself before you install it. How we verify

?

Questions

How do I install a skill?

Every product page includes a copy-paste install prompt. Paste it into your Muse and it sets the skill up for you — no manual configuration.

Where does my money go?

Straight to the seller. Skill Harbor never processes payments: checkout happens on the seller’s own page, usually Stripe.

What does the ✓ next to a creator’s name mean?

It means we confirmed the identity of the person behind the listing. It says nothing about the code itself — always check a skill before installing it.