← Docs

inbox.dog for OpenClaw

Full Gmail tools for your OpenClaw agent. Read, search, send via OAuth. CASA Tier 2 certified. Self-host optional.

At a glance

  • Path A — MCP config (recommended): Use if your OpenClaw version supports mcpServers.
  • Path B — Workspace Skill: Use if mcpServers is unsupported.

Both paths expose: get_profile, read_emails, search_emails, read_email, send_email.

Path A: MCP config (recommended)

1) Add MCP server

{
  "mcpServers": {
    "inbox-dog": {
      "url": "https://inbox.dog/mcp"
    }
  }
}

2) Restart gateway

openclaw gateway restart

3) Connect OAuth (durable mode)

Open this URL in your browser (replace YOUR_CLIENT_ID):

https://inbox.dog/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Finbox.dog%2Fconnect%2Foauth&scope=email&prompt=consent

Why prompt=consent? This ensures Google returns a refresh token. Without it, you get an access token that expires in ~1 hour with no way to renew. The server already sets access_type=offline automatically.

Complete consent and copy the one-time code from the success page.

4) Verify

Test both profile and search:

What's my email address?
Search my email for "welcome"

If both return real data, you're production-ready. If the first works but search fails, restart the gateway and retry.

Path B: Workspace Skill

Use this if your OpenClaw runtime doesn't support mcpServers.

1) Create skill folder

mkdir -p ~/.openclaw/workspace/skills/inbox-dog

2) Add skill file

Create ~/.openclaw/workspace/skills/inbox-dog/SKILL.md with:

# inbox.dog — Gmail for Agents

Gmail read, write, search, and send via OAuth. CASA Tier 2 certified.

## Setup

This skill requires environment variables:
- `INBOXDOG_CLIENT_ID` — your API key client ID
- `INBOXDOG_CLIENT_SECRET` — your API key secret

Get both at https://inbox.dog/connect

## Tools

Run the MCP server: `npx -y inbox.dog mcp`

### get_profile
Returns the authenticated user's Gmail profile (email, threads count).

### read_emails
Read recent emails from the inbox.
- `maxResults` (optional, default 10): number of emails to return

### read_email
Read a specific email by ID.
- `id` (required): the email message ID

### search_emails
Search Gmail with a query string.
- `query` (required): Gmail search query (same syntax as Gmail search bar)
- `maxResults` (optional, default 10): number of results

### send_email
Send an email.
- `to` (required): recipient email address
- `subject` (required): email subject
- `body` (required): email body (plain text)
- `cc` (optional): CC recipients
- `bcc` (optional): BCC recipients

## Auth Flow

On first use, the user is prompted to authorize Gmail access via OAuth.
Tokens refresh automatically — no manual re-auth needed.

3) Create API key

curl -s -X POST https://inbox.dog/api/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "openclaw"}' | jq

4) Add credentials

{
  "skills": {
    "entries": {
      "inbox-dog": {
        "enabled": true,
        "env": {
          "INBOXDOG_CLIENT_ID": "id_your_client_id_here",
          "INBOXDOG_CLIENT_SECRET": "sk_your_client_secret_here"
        }
      }
    }
  }
}

5) Restart gateway

openclaw gateway restart

6) Connect OAuth (durable mode)

https://inbox.dog/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Finbox.dog%2Fconnect%2Foauth&scope=email&prompt=consent

Complete consent and copy the one-time code. Paste it when your OpenClaw agent asks.

7) Verify

What's my email address?
Search my email for "welcome"

Expected OAuth outcome

After exchanging the code for tokens, you should see:

  • ✅ access_token — present
  • ✅ expires_in — present
  • ✅ email — present
  • ✅ refresh_token — non-empty (required for durable installs)

If refresh_token is empty: Re-run OAuth with prompt=consent to force a fresh consent flow. This is the most common cause of "connected but not durable" installs.

Verification checklist

Run through these after setup to confirm you're production-ready, not just partially connected.

☐

Integration loaded — MCP or skill enabled, client_id and client_secret present in config

☐

Gateway restarted — config changes don't take effect until restart

☐

OAuth completed — used hosted redirect, exchanged code for tokens

☐

Refresh token present — if empty, re-auth with prompt=consent. Without it you're connected but not durable (~1 hour expiry)

☐

Profile works — ask "What's my email address?" and get a real answer

☐

Search works — ask "Search my email for welcome" and get results

All six checked? You're production-ready. If profile works but search doesn't, restart the gateway. If refresh token is missing, you're connected but will lose access in ~1 hour — re-auth with prompt=consent.

Troubleshooting

mcpServers rejected / unsupported

Use Path B (Workspace Skill).

OAuth code fails

Codes are one-time use and expire quickly. Exchange promptly. If it fails, start a new auth flow.

"Connected" but email tools unavailable

Restart gateway, re-run verification prompts. Confirm credentials are in the active config.

No refresh token

Re-run OAuth with prompt=consent. Without a refresh token, access expires in ~1 hour.

Security

  • OAuth + PKCE flow — no Gmail passwords handled
  • CASA Tier 2 certified for restricted Gmail scopes
  • Prefer hosted redirect URIs (avoid localhost confusion for remote setups)
  • Self-host available (MIT)