Connect Gmail to send emails from Telegram

What this enables

From Telegram, you can compose and send emails by speaking or typing to the bot. For example:

• "Email [email protected] saying I will miss the 3pm standup"
• "Reply to my last email from Sarah and confirm Tuesday works"
• "Send the meeting notes from earlier to the design team"

Every send shows a preview in Telegram with the From, To, Cc, Bcc, Subject, and Body fields fully visible. You tap Send to confirm, or Cancel to abort. The email leaves your Gmail account and appears in your Sent folder as if you had clicked Send in Gmail's web UI.

What we ask permission for

When you complete the consent flow, Google shows you exactly one permission request:

Send email on your behalf

That maps to the https://www.googleapis.com/auth/gmail.send OAuth scope. It is the narrowest permission Google offers for this use case. It does not grant any ability to:

• Read your inbox or any individual message
• Modify, delete, archive, or label messages
• Access your contacts or address book
• Change your Gmail settings or signature
• See your message metadata, threads, or search

If you also use Anthropic's Gmail Connector inside Claude, that connector handles reading and drafting independently of CodePulse — the two operate on separate permissions and neither sees the other's tokens.

How to connect

One-time setup takes about 15 seconds, with no manual app-switching:

1. In Telegram, type /connect_gmail.
2. CodePulse replies with a card explaining what you are about to authorize. Tap "Connect Gmail".
3. A scope-disclosure panel opens inside Telegram (this is a Telegram Mini App, not a browser). Tap "Continue with Google".
4. Telegram hands the sign-in to your phone's real browser session — iOS opens it in Safari View, Android in Chrome Custom Tab, desktop in your default browser. Because this is your real browser, your existing Gmail sign-in carries over: in most cases you skip straight to the consent screen with no re-login.
5. Tap Allow on the single-permission consent screen ( https://www.googleapis.com/auth/gmail.send).
6. The success page shows "✅ Gmail connected. Returning to Telegram…" and auto-redirects you back to the CodePulse chat. On mobile this happens via the t.meuniversal link — Telegram opens automatically; you do not need to switch apps manually.
7. Back in Telegram, the bot has already posted "✅ Connected: [email protected]" and you can immediately try sending.

Why the "real browser" step? Google blocks OAuth inside embedded WebViews (their policy since 2017). Telegram's Mini App runs inside a WebView, so the sign-in has to be handed off. The hand-off is one tap and the return trip is automatic.

What you will see when sending

Every email that CodePulse is about to send produces an approval card in Telegram. The card always shows:

• From— which of your connected accounts will be the sender
• To— primary recipient(s)
• Cc and Bcc— if any were specified
• Subject— the proposed subject line
• Body— the full message body, budget-aware so long messages stay visible (subject and recipients are kept short so the body gets the most space)

You tap Send to dispatch, or Cancelto abort. There is no auto-send mode for email — the always-ASK policy is enforced server-side and cannot be bypassed by learned approval patterns or auto-approve configurations.

Multi-account support

You can connect more than one Gmail account — for example a personal address and a Workspace work address — and CodePulse will let you specify which one to send from. To add an account, run /connect_gmail again with a different Google account signed in. To list connected accounts, type /email_status.

When you compose an email, you can name the sender in your message ("Send from work@… to John…") or let CodePulse use the most recently connected account by default.

Privacy and security

Your Gmail credentials never leave your machine. The exact security model:

• Local-only storage— the OAuth refresh token is encrypted with AES-256-GCM and written to your local SQLite database. CodePulse's servers never receive or store your refresh token.
• Per-install encryption key— the encryption key is generated when you install CodePulse and stays on that machine. A different install has a different key; an attacker who exfiltrates the SQLite file cannot decrypt it without also extracting the key from the same machine.
• Send-only permission— even if your machine were compromised, the worst an attacker could do is send emails on your behalf (limited by Gmail's daily send caps). They could not read your inbox, exfiltrate historical mail, or change your account.
• Pseudonymized logs— the local audit log stores a one-way HMAC hash of your email address, never the plaintext. Recipient lists, subjects, and bodies are never logged.

For the full data-handling details, see our privacy policy.

Beta phase note

Until our CASA Tier 2 verification clears, Google operates the CodePulse OAuth client in Test User mode. This has two user-visible consequences:

• Up to 100 specific email addressescan use the feature during the beta. If you receive a "CodePulse is being tested" warning from Google during the consent flow, your address has not yet been added to the test-user list. Contact us at [email protected] with the Gmail address you want to use.
• Refresh tokens expire after 7 days. You will see a re-authentication prompt in Telegram roughly weekly until verification clears. Tap /connect_gmail again to refresh the connection (no data is lost).

After CASA verification both limits go away — refresh tokens become indefinite and any Gmail user can connect.

Workspace users (custom domains)

Gmail send works identically for personal @gmail.com addresses and Google Workspace@yourdomain.com addresses. There is one important caveat: your Workspace administrator can block third-party OAuth at the organization level.

If your admin has restricted "Apps with access to your account," the consent flow will fail with a message starting "Access blocked: your admin has restricted access…". To unblock:

• Ask your admin to either allow CodePulse specifically in their API controls, or relax the third-party app policy.
• Or use a personal Gmail address that is not subject to the admin policy.

We cannot work around Workspace admin restrictions — they are intentional security controls operated by your organization.

Disconnecting

You can revoke CodePulse's access at any time:

• From Telegram: type /disconnect_gmail. If you have one account connected, the bot confirms and deletes the local credentials and calls Google's revocation endpoint to invalidate them server-side. If you have multiple accounts, a picker appears so you can choose which to disconnect.
• From Google: visit Google Account › Security › Third-party apps with account access, find CodePulse, and click "Remove access."

Either path is sufficient. Disconnecting from Telegram is slightly faster (it tells both your local install AND Google in one step); disconnecting from Google works even if you have uninstalled CodePulse.

Troubleshooting

"Gmail send not enabled on this install" in the entry card

Your CodePulse install is missing the CODEPULSE_CREDENTIAL_KEY environment variable. Run /diagnosticsin Telegram for the exact location of your install's .env file and follow the steps it shows.

"Setup timed out" after I closed the browser

The OAuth flow waits 5 minutes for you to complete Allow/Deny. If you close the browser tab without tapping Allow, or never tap Continue with Google on the scope panel, the bot eventually shows the timeout card. Tap /connect_gmail to start over.

The Continue button does not open anything

If sign-in didn't open after you tapped Continue with Google, the scope panel now shows a visible "Open Google sign-in in your browser" fallback link. Tap it to launch the consent flow in your default browser. This happens on a small subset of Android setups where Telegram's "Inline browser" preference keeps links inside Telegram (Google blocks OAuth in any in-app browser, so the fallback to a real browser is required).

To avoid this entirely, disable Telegram's in-app browser setting: Settings → Chats → In-app browser (Android). On iOS this isn't a user setting; Telegram always uses SafariViewController which works correctly.

The Continue button is missing entirely

The scope panel uses Telegram's Mini App feature. If you have a very old Telegram client (pre-2022), Mini App support may be missing. Update Telegram to the latest version. On a fresh, up-to-date Telegram install this is rare.

Google says "Disallowed_useragent" or 403

You should never see this with v2.3.151 — the sign-in is explicitly handed off to your real browser to avoid this exact restriction. If you do see it, you may be on an older CodePulse build. Update the app from the system tray menu and try again.

"Send failed: token expired" mid-session

Google rotated or invalidated your refresh token (most often this happens at the 7-day Test User boundary, or if you revoked access from Google's account UI). Tap /connect_gmailto reconnect — the queued send is not automatically retried, but you can resend after reconnecting.

"Access blocked: your admin has restricted access"

See Workspace usersabove — your Google Workspace administrator has not allowed third-party OAuth for this scope.

Still stuck?

Email [email protected] with a description of what you tried and the exact error message. Include your CodePulse version (visible in the system-tray menu) so we can match the behavior to the right release.