Wiro Docs Gmail Integration
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:

  • 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

Setup

Step 1: Enable 2-Step Verification

  1. Sign in to the Google account.
  2. 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 — 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 start.sh and NOT wired to the runtime. The actual polling cadence comes from the scheduled skill cron-gmail-checker under customskills[] (a cron wrapper that invokes the built-in gmail-check platform skill). To change how often the inbox is polled, update the cron-gmail-checker skill's interval via POST /UserAgent/CustomSkillUpsert — see Agent Skills.

Naming: the platform skill (the IMAP-speaking module loaded from skills/gmail-check/SKILL.md) is gmail-check. The cron wrapper (an entry in customskills[] that schedules inbox polling and references gmail-check internally) is cron-gmail-checker (prefixed with cron- to mark it as a scheduled task). When skills.gmail-check is disabled on the template, the cron wrapper early-returns with HEARTBEAT_OK.

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 gmail-check skill uses IMAP:

  • Host: imaps://imap.gmail.com:993/INBOX
  • Auth: --user "$GMAIL_ACCOUNT:$GMAIL_APP_PASSWORD" (Basic-style)
  • Polls on the configured interval, processes new messages per agent rules

Env vars inside the agent container (exported only when gmail-check skill is enabled and account is set):

  • GMAIL_ACCOUNT ← credentials.gmail.account
  • GMAIL_APP_PASSWORD ← credentials.gmail.apppassword

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.