PHPackages carmelosantana/coqui-toolkit-google-gmail - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Mail & Notifications](/categories/mail) 4. / 5. carmelosantana/coqui-toolkit-google-gmail ActiveLibrary[Mail & Notifications](/categories/mail) carmelosantana/coqui-toolkit-google-gmail ========================================= Google Gmail toolkit for Coqui — read, send, label, and draft emails via the Gmail REST API v0.1.1(1mo ago)00MITPHPPHP ^8.4CI passing Since Apr 9Pushed 1mo agoCompare [ Source](https://github.com/carmelosantana/coqui-google-gmail)[ Packagist](https://packagist.org/packages/carmelosantana/coqui-toolkit-google-gmail)[ RSS](/packages/carmelosantana-coqui-toolkit-google-gmail/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (1)Dependencies (4)Versions (3)Used By (0) Coqui Toolkit: Google Gmail =========================== [](#coqui-toolkit-google-gmail) Gmail integration toolkit for [Coqui Bot](https://github.com/AgentCoqui/coqui) — read, send, label, and draft emails via the Gmail REST API with OAuth2 authentication. Features -------- [](#features) - **OAuth2 browser-based login** — secure authentication with PKCE, no passwords stored - **Full message management** — list, search (Gmail query syntax), read, send, reply, forward, trash, delete - **Label management** — list labels with unread counts, create/update/delete custom labels, modify message labels - **Draft management** — create, update, send, and delete email drafts - **Credential guard** — Coqui's credential system prompts for OAuth2 client ID/secret automatically - **Tool gating** — destructive operations (send, delete, trash, etc.) require user confirmation Requirements ------------ [](#requirements) - PHP 8.4+ - A Google Cloud project with the Gmail API enabled - OAuth2 Desktop app credentials (Client ID + Client Secret) Installation ------------ [](#installation) ``` composer require coquibot/coqui-toolkit-google-gmail ``` Coqui discovers the toolkit automatically on next boot. Google Cloud Setup ------------------ [](#google-cloud-setup) Before using the toolkit, you need to create OAuth2 credentials in Google Cloud Console: ### 1. Create a Google Cloud Project [](#1-create-a-google-cloud-project) 1. Go to [Google Cloud Console](https://console.cloud.google.com/) 2. Create a new project (or use an existing one) 3. Note the project name for later ### 2. Enable the Gmail API [](#2-enable-the-gmail-api) 1. Navigate to **APIs & Services > Library** 2. Search for "Gmail API" 3. Click **Enable** ### 3. Configure the OAuth Consent Screen [](#3-configure-the-oauth-consent-screen) 1. Go to **APIs & Services > OAuth consent screen** 2. Choose **External** user type (or **Internal** for Google Workspace) 3. Fill in the required fields: - App name: e.g. "Coqui Gmail" - User support email: your email - Developer contact: your email 4. Add scopes: - `https://www.googleapis.com/auth/gmail.modify` - `https://www.googleapis.com/auth/gmail.compose` 5. Add your Google account as a test user (required while in "Testing" status) 6. Save ### 4. Create OAuth2 Desktop Credentials [](#4-create-oauth2-desktop-credentials) 1. Go to **APIs & Services > Credentials** 2. Click **Create Credentials > OAuth client ID** 3. Application type: **Desktop app** 4. Name: e.g. "Coqui Gmail Desktop" 5. Click **Create** 6. Copy the **Client ID** and **Client Secret** ### 5. Configure Credentials in Coqui [](#5-configure-credentials-in-coqui) Tell Coqui your OAuth2 credentials: ``` You: Set my Gmail credentials Coqui: credentials(action: "set", key: "GMAIL_CLIENT_ID", value: "your-client-id.apps.googleusercontent.com") Coqui: credentials(action: "set", key: "GMAIL_CLIENT_SECRET", value: "your-client-secret") ``` Or set them as environment variables: ``` export GMAIL_CLIENT_ID="your-client-id.apps.googleusercontent.com" export GMAIL_CLIENT_SECRET="your-client-secret" ``` ### 6. Authenticate [](#6-authenticate) ``` You: Connect my Gmail account Coqui: gmail_auth(action: "login") → Opens browser for Google sign-in → Stores tokens securely in .workspace/.gmail-tokens/ ``` Tools ----- [](#tools) ### gmail\_auth [](#gmail_auth) Manage OAuth2 authentication lifecycle. ActionDescriptionGated`status`Check if connected to GmailNo`login`Open browser for Google OAuth2 sign-inNo`revoke`Disconnect Gmail and delete tokensYes### gmail\_message [](#gmail_message) Full email message management. ActionDescriptionGated`list`List inbox messages (with optional label filter)No`search`Search messages using Gmail query syntaxNo`get`Read full message contentNo`send`Send a new emailYes`reply`Reply to a message (preserves threading)Yes`forward`Forward a message to another recipientYes`trash`Move message to trashYes`untrash`Restore message from trashYes`delete`Permanently delete a messageYes`modify`Add/remove labels (mark read, star, archive, etc.)Yes### gmail\_label [](#gmail_label) Gmail label management. ActionDescriptionGated`list`List all labels with message/thread countsNo`get`Get label details and countsNo`create`Create a custom labelYes`update`Rename or change label visibilityYes`delete`Delete a custom labelYes### gmail\_draft [](#gmail_draft) Email draft management. ActionDescriptionGated`list`List all draftsNo`get`Read draft contentNo`create`Create a new draftNo`update`Update an existing draftNo`send`Send a draft as an emailYes`delete`Delete a draftYesGmail Search Syntax ------------------- [](#gmail-search-syntax) The `search` action supports Gmail's full query syntax: OperatorExampleDescription`from:``from:user@example.com`Messages from sender`to:``to:user@example.com`Messages to recipient`subject:``subject:meeting`Subject contains word`is:unread``is:unread`Unread messages`is:starred``is:starred`Starred messages`has:attachment``has:attachment`Has attachments`after:``after:2024/01/01`After date`before:``before:2024/12/31`Before date`label:``label:important`Has label`in:``in:inbox`In location`larger:``larger:5M`Larger than size`filename:``filename:pdf`Attachment filenameCombine operators: `from:boss@work.com is:unread subject:urgent after:2024/06/01` Usage Examples -------------- [](#usage-examples) ### Check for unread messages [](#check-for-unread-messages) ``` You: Do I have any unread emails? Coqui: gmail_message(action: "search", query: "is:unread", max_results: 10) → Shows unread messages with subject, sender, and date ``` ### Read and reply [](#read-and-reply) ``` You: Read the latest email from john@example.com and draft a reply Coqui: gmail_message(action: "search", query: "from:john@example.com", max_results: 1) Coqui: gmail_message(action: "get", message_id: "...") Coqui: gmail_message(action: "reply", message_id: "...", body: "Thanks for your email, John...") ``` ### Organize inbox [](#organize-inbox) ``` You: Archive all read messages in my inbox Coqui: gmail_message(action: "search", query: "in:inbox -is:unread", max_results: 50) Coqui: gmail_message(action: "modify", message_id: "...", remove_label_ids: "INBOX") ``` ### Create and send a draft [](#create-and-send-a-draft) ``` You: Draft an email to the team about the meeting Coqui: gmail_draft(action: "create", to: "team@company.com", subject: "Team Meeting", body: "...") Coqui: gmail_draft(action: "get", draft_id: "...") // Review Coqui: gmail_draft(action: "send", draft_id: "...") // Send when ready ``` Architecture ------------ [](#architecture) ``` src/ ├── GmailToolkit.php # ToolkitInterface — registers all tools, provides guidelines ├── GmailClient.php # HTTP client wrapper for Gmail REST API ├── Auth/ │ ├── OAuthHandler.php # OAuth2 browser flow with PKCE + token storage │ └── OAuthException.php # Auth-specific exceptions ├── Exception/ │ ├── GmailApiException.php # API error exceptions │ └── GmailAuthException.php # Authentication exceptions └── Tool/ ├── AuthTool.php # gmail_auth — OAuth lifecycle ├── MessageTool.php # gmail_message — message CRUD + search ├── LabelTool.php # gmail_label — label management └── DraftTool.php # gmail_draft — draft management ``` Token Storage ------------- [](#token-storage) OAuth2 tokens are stored in `.workspace/.gmail-tokens/default.json` with `0600` file permissions. Tokens are: - **Automatically refreshed** when they expire (using the refresh token) - **Never exposed** to the LLM — only the `OAuthHandler` and `GmailClient` access them - **Revocable** via `gmail_auth(action: "revoke")` which also calls Google's revocation endpoint Security -------- [](#security) - OAuth2 with PKCE protects against authorization code interception - Client credentials are managed via Coqui's `.env`-based credential system - Tokens stored with restrictive file permissions (`0600`) - All destructive operations (send, delete, modify) are gated and require user confirmation - The toolkit never exposes email content to logs or audit trails beyond what the agent processes Development ----------- [](#development) ``` # Install dependencies composer install # Run tests ./vendor/bin/pest # Static analysis ./vendor/bin/phpstan analyse ``` License ------- [](#license) MIT ### Health Score 37 — LowBetter than 83% of packages Maintenance94 Actively maintained with recent releases Popularity0 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~1 days Total 2 Last Release 32d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/597820?v=4)[Carmelo Santana](/maintainers/carmelosantana)[@carmelosantana](https://github.com/carmelosantana) --- Top Contributors [![carmelosantana](https://avatars.githubusercontent.com/u/597820?v=4)](https://github.com/carmelosantana "carmelosantana (3 commits)") --- Tags googleemailtoolkitphp-agentscoquigmail ### Code Quality TestsPest Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/carmelosantana-coqui-toolkit-google-gmail/health.svg) ``` [![Health](https://phpackages.com/badges/carmelosantana-coqui-toolkit-google-gmail/health.svg)](https://phpackages.com/packages/carmelosantana-coqui-toolkit-google-gmail) ``` ### Alternatives [symfony/fake-sms-notifier Fake SMS (as email or log during development) Notifier Bridge. 27754.2k1](/packages/symfony-fake-sms-notifier)[swissup/module-email Magento2 email providers integration (smtp, mandrill, amazon ses) 1412.8k1](/packages/swissup-module-email) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)