# Gmail Integration Connect your agent to a Gmail inbox using a Google App Password for IMAP access. ## Overview The Gmail integration uses IMAP with Basic authentication backed by a Google App Password. Agents can monitor the inbox, parse incoming messages, and trigger actions. **Skills that use this integration:** - `int-gmail-check`: Poll Gmail inbox on a schedule, parse messages, route to actions **Agents that typically enable this integration:** - Blog Content Editor (inbox-triggered workflows) - Newsletter Manager (test sends) - Support / App Review agents (operator notifications) ## Availability | Mode | Status | Notes | |------|--------|-------| | App Password | Available | Works on any Gmail account with 2-Step Verification enabled. | ## Prerequisites - **A Wiro API key** (see [Authentication](/docs/authentication)). - **A deployed agent** (see [Agent Overview](/docs/agent-overview)). - **A Gmail account** with **2-Step Verification** enabled. ## Setup ### Step 1: Enable 2-Step Verification 1. Sign in to the Google account. 2. [myaccount.google.com/security](https://myaccount.google.com/security). 3. Under **How you sign in to Google**, turn on **2-Step Verification**. ### Step 2: Create an App Password 1. Same Security page → **App passwords** (appears once 2-Step Verification is on). 2. Create a new App Password, label it "Wiro agent". 3. Copy the 16-character password (format: `xxxx xxxx xxxx xxxx`). Spaces are cosmetic, and Wiro accepts either form. ### Step 3: Save to Wiro ```bash curl -X POST "https://api.wiro.ai/v1/UserAgent/CredentialUpsert" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "useragentguid": "your-useragent-guid", "fields": [ { "credentialkey": "gmail", "fieldname": "account", "fieldvalue": "agent@yourcompany.com" }, { "credentialkey": "gmail", "fieldname": "apppassword", "fieldvalue": "xxxx xxxx xxxx xxxx" } ] }' ``` Only `account` and `apppassword` are writable by API callers. `credentials.gmail.interval` (when present in some templates) is not used by the agent runtime. How often the inbox is read comes from the scheduled task that uses Gmail, `cs-cron-blog-gmail-checker` on the blog presets. To change it, update that task's `interval` via `POST /UserAgent/CustomSkillUpsert` (see [Agent Skills](/docs/agent-skills#managing-scheduled-tasks)). > **Naming:** the skill is `int-gmail-check`. The scheduled task that reads the inbox on the blog presets is `cs-cron-blog-gmail-checker` (`cs-cron-` marks a scheduled task). If `int-gmail-check` is off or Gmail is not connected, the task does nothing on its runs. ### Step 4: Start the agent ```bash curl -X POST "https://api.wiro.ai/v1/UserAgent/Start" \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "guid": "your-useragent-guid" }' ``` ## Credential Fields | Field | Type | Editable | Description | |-------|------|----------|-------------| | `account` | string | Yes | Full Gmail address (e.g. `agent@company.com`). | | `apppassword` | string | Yes | 16-character Google App Password. Spaces allowed. | | `interval` | cron string | **No** (template-controlled) | Polling frequency. Example: `*/8 * * * *` (every 8 minutes). | ## Credentials schema (as returned by `POST /UserAgent/Detail`) ```json "gmail": { "_connected": false, "optional": true, "extra": false, "account": "", "apppassword": "" } ``` ## Runtime Behavior The `int-gmail-check` skill reads the inbox over IMAP: - Host: `imaps://imap.gmail.com:993/INBOX` - Auth: the Gmail address and app password you saved (`account` / `apppassword`) - Runs on the schedule of the agent's Gmail scheduled task and processes new messages per the agent's rules The skill is active only when it is enabled and `account` is set. ## Troubleshooting - **"Invalid credentials" when IMAP connects:** Wrong App Password, or 2-Step Verification was turned off (which invalidates all App Passwords). Regenerate. - **Agent can't see messages older than ~30 days:** IMAP folder defaults. For broader scope, your agent may need to switch to "All Mail". Ask support. - **"Less Secure Apps" mentioned anywhere:** Google removed that option in 2022. App Password is the only supported path for IMAP/SMTP. ## Related - [Agent Credentials & OAuth](/docs/agent-credentials) - [Agent Overview](/docs/agent-overview) - [Agent Skills](/docs/agent-skills) - [Google App Passwords help](https://support.google.com/accounts/answer/185833)