This section as Markdown: View Download

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 — Authentication.
A deployed agent — Agent Overview.
A Gmail account with 2-Step Verification enabled.

Setup

Step 1: Enable 2-Step Verification

Sign in to the Google account.
myaccount.google.com/security.
Under How you sign in to Google, turn on 2-Step Verification.

Step 2: Create an App Password

Same Security page → App passwords (appears once 2-Step Verification is on).
Create a new App Password, label it "Wiro agent".
Copy the 16-character password (format: xxxx xxxx xxxx xxxx). Spaces are cosmetic — Wiro accepts either form.

Step 3: Save to Wiro

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": "[email protected]" },
      { "credentialkey": "gmail", "fieldname": "apppassword", "fieldvalue": "xxxx xxxx xxxx xxxx" }
    ]
  }'

Only account and apppassword are editable. 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.

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

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. `[email protected]`).
`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`)

"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.