Email (Gmail OAuth)

🟢 Runtime-ready — Gmail API with OAuth 2.0 device flow. Streaming via a background gmail-inbound-daemon worker that polls threads and dispatches received messages.

What you get

• Authenticated via OAuth — users grant access without storing credentials
• Streaming edits — messages are updated live (like chat) via a background worker
• Webhooks — optional pubsub topic for instant delivery (requires Cloud Pub/Sub setup)
• Thread-aware — replies stay in the same conversation thread
• Recipient override — channel param routes to a different Gmail account

Setup

1. Create a Google Cloud project

1. Go to Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable the Gmail API:
   • Search for "Gmail API" in the APIs & Services library
   • Click "Enable"
4. Create an OAuth 2.0 consent screen:
   • Go to "OAuth consent screen" → Create
   • Choose "External" user type
   • Fill in app name, support email, and developer contact
   • Add the scope https://www.googleapis.com/auth/gmail.modify
5. Create an OAuth 2.0 client ID:
   • Go to "Credentials" → Create Credential → OAuth client ID
   • Choose "Desktop app"
   • Download the JSON (you'll need the client ID + secret)

2. Provide credentials to Minara

Easy way — ask the agent:

"connect Gmail to send me notifications using OAuth"

The agent guides you through the device flow to grant access.

Manual way:

minara auth messaging add email-gmail

Or directly in your project .env:

GMAIL_OAUTH_CLIENT_ID=your-client-id.apps.googleusercontent.com
GMAIL_OAUTH_CLIENT_SECRET=your-client-secret
[email protected]

3. (Optional) Enable instant webhooks

To receive replies in real-time instead of polling:

1. Create a Cloud Pub/Sub topic for Gmail notifications
2. Set up a push subscription pointing to your Minara instance
3. Add to .env:

GMAIL_PUBSUB_TOPIC=projects/your-project/topics/gmail-notifications

Inbound messages

The background gmail-inbound-daemon worker polls your inbox every 30 seconds (configurable via GMAIL_POLL_INTERVAL_SEC) and dispatches received messages to workflows or the agent chat.

Thread handling: replies are routed back to the workflow or chat session that originally sent the message, maintaining conversation history.

Rate limits

• Send: 100 emails per user per minute (Gmail API limit)
• Receive: polling every 30 seconds by default; Pub/Sub instant (if configured)
• Thread read: 1 call per received message

Troubleshooting

"Authorization required" after setup

• The OAuth token expired. Run minara auth messaging test email-gmail to refresh.

Not receiving replies

• Check that the daemon is running: minara learn cron should show gmail-inbound-daemon as active
• Verify the Pub/Sub topic is configured correctly (if using webhooks)
• Check agent logs: tail -f ~/.minara/logs/agent.log | grep gmail

Differences from SMTP email