By Oliver · AI Architect, BuildAClaw · May 8, 2026 · 9 min read

How to Give Your AI Agent Access to Your Email (Safely)

Email management is the #1 workflow OpenClaw users automate first — and the #1 place I see setups go sideways. Not because the agent misbehaved, but because someone handed it a master key when it only needed a mailbox key. Here's how to do it right.

One of the most-upvoted OpenClaw threads I've seen described it perfectly: the user connected their Microsoft 365 account, and within two weeks their agent was deleting, archiving, auto-drafting replies, and flagging priority messages — all running on their own machine, zero cloud middleman. They described it as life-changing.

But buried in the replies was a warning from another user: "If you don't even know those basics, it's probably best to ditch the idea altogether. It is so dangerous and people take it too easy." That comment has stuck with me. They weren't wrong — but they also weren't helpful. The answer isn't "don't do it." The answer is "do it with the right access model."

This guide gives you exactly that: the right access model, the right OAuth scopes, and the guardrails to put in place before your agent touches a single message.

Why Email Is the First Thing People Automate (and Why It's High Stakes)

Email sits at the center of nearly every business workflow. It's where deals land, where support tickets arrive, where vendors send invoices, and where your most sensitive conversations live. When you automate it well, you reclaim 2–4 hours per day. When you automate it badly, you can accidentally delete a contract, expose a thread to the wrong person, or — worst case — let a compromised agent credential sit on a third-party server for months.

The right alternative is OAuth 2.0 with scoped permissions. It's what Gmail and Microsoft 365 both use natively, and it's what OpenClaw supports out of the box. Let's walk through exactly what that means and how to set it up.

OAuth vs. App Passwords: The Only Comparison That Matters

Before you touch any configuration, you need to understand why these two credential types are not interchangeable.

An app password is essentially a second password for your account. If it leaks — if your agent's config file ends up in a Git repo, if your Mac Mini gets compromised, if a process dumps it to a log — an attacker gets full access to your email. Every draft, every sent message, every attachment.

An OAuth token, by contrast, is scoped and time-limited. You tell Google or Microsoft exactly what the agent is allowed to do (read only? send only? manage labels?), and nothing beyond that is accessible. You can revoke it in 10 seconds from your account settings, without changing your password, without notifying anyone, without any downstream side effects.

Setting Up Gmail OAuth with OpenClaw

Google's OAuth flow for Gmail requires a one-time setup in Google Cloud Console. This takes about 15 minutes and you only do it once per Google account you want to connect.

Step 1: Create a Google Cloud Project

Go to console.cloud.google.com, create a new project (name it something like "OpenClaw Agent"), and enable the Gmail API from the API Library. This takes under 2 minutes.

Step 2: Configure OAuth Consent Screen

Under APIs & Services → OAuth consent screen, select "External" user type (even for personal accounts), fill in your app name and your email as both the developer and support contact. You don't need a privacy policy URL for personal/internal use.

Step 3: Create OAuth Credentials

Under APIs & Services → Credentials, click "Create Credentials" → "OAuth client ID." Choose "Desktop app" as the application type. Download the JSON credentials file — this contains your client_id and client_secret.

Step 4: Choose Your Scopes (This Is the Critical Part)

When OpenClaw initiates the OAuth flow, it will request specific Gmail scopes. Here's what each one means — only grant what you actually need:

• gmail.readonly — Read email only. Cannot send, delete, or modify anything. Start here.
• gmail.send — Send email only. Cannot read inbox or modify messages.
• gmail.labels — Create and modify labels. Safe for triage workflows.
• gmail.modify — Read, label, archive, mark as read/unread. Cannot permanently delete.
• mail.google.com — Full access. Only use this if you've verified your agent's behavior in a sandbox first.

For a first deployment, I recommend starting with gmail.readonly + gmail.labels. Watch the agent work for 48 hours. Then add gmail.modify once you've confirmed it's categorizing correctly. Add send permissions last, only after you've reviewed a batch of draft outputs.

Step 5: Store the Token Locally

OpenClaw stores your OAuth refresh token in its local config directory — on your machine, not on any BuildAClaw server. On Mac, this is typically ~/.config/openclaw/credentials/. Make sure that directory has 700 permissions (chmod 700 ~/.config/openclaw/credentials) so only your user can read it.

Setting Up Microsoft 365 / Outlook with OpenClaw

The Microsoft flow uses Azure Active Directory (now called Microsoft Entra ID) and is structurally identical to Google's flow — it just lives in a different portal.

Register an App in Azure

Go to portal.azure.com → Azure Active Directory → App registrations → New registration. Name it "OpenClaw Agent," select "Accounts in this organizational directory only" (or "personal accounts" for Outlook.com), and set the redirect URI to http://localhost:8080 for the desktop OAuth flow.

Add API Permissions

Under your app registration, go to API permissions → Add a permission → Microsoft Graph. The equivalent Microsoft scopes to Gmail's are:

• Mail.Read — Read email. Start here.
• Mail.ReadWrite — Read + modify + archive. Equivalent to gmail.modify.
• Mail.Send — Send only. Add this separately when ready.
• MailboxSettings.Read — Read mailbox config (useful for understanding folder structure).

Create a client secret under Certificates & secrets, copy it immediately (it's shown once), and store it in your OpenClaw config. Microsoft tokens expire and auto-refresh via the refresh token — you won't need to re-authenticate unless you revoke access manually.

Least-Privilege in Practice: A Scope Rollout Plan

Don't grant all permissions on day one. Treat email agent access like you'd treat a new employee — start with read-only, expand as trust is established.

Week 1 — Observe only: Grant gmail.readonly (or Mail.Read). Configure OpenClaw to categorize and summarize incoming email but take no action. Review its output daily. Is it correctly identifying priority senders? Is it miscategorizing anything important?

Week 2 — Label and archive: Add gmail.labels (or Mail.ReadWrite without send). Let the agent move newsletters to a folder, label invoices, and archive automated notifications. These are low-stakes, reversible actions.

Week 3 — Draft replies: Enable draft creation. Review every draft before sending manually. This is the most valuable phase for training your prompts — you'll see exactly where the agent's tone or judgment diverges from yours.

Week 4+ — Supervised send: Only after you've reviewed 50+ drafts and found fewer than 5% needed significant edits should you consider enabling autonomous send — and only for specific categories (e.g., automated confirmations to known vendors, not replies to new contacts).

Security Guardrails Before You Go Live

OAuth scopes limit what your agent can do. These additional guardrails limit what it will do in edge cases.

1. Allowlist Domains for Outbound Actions

Configure OpenClaw's email tool with an explicit sender allowlist — a list of domains or addresses where the agent is permitted to take write actions (archive, label, draft). If an email arrives from an unknown domain, the agent logs it and flags it for human review instead of acting autonomously. This prevents a malicious email crafted to manipulate agent behavior ("prompt injection via email") from triggering unintended actions.

2. Never Store Credentials in Plaintext Config Files

Your OAuth client secret and refresh token should live in environment variables or your system's keychain, not in a .yaml or .json file you might accidentally commit. On Mac, use Keychain Access or the security CLI to store secrets. OpenClaw can read from environment variables natively — use that path.

3. Set Up a Revocation Bookmark

Bookmark these two URLs right now, before you connect anything:

• Gmail: myaccount.google.com/permissions
• Microsoft 365: myapplications.microsoft.com

If anything ever looks wrong — unexpected sent items, missing emails, strange activity — those pages let you revoke access in under 10 seconds. No password change required.

4. Log Agent Actions Locally

Configure OpenClaw to write a local action log for every email operation: timestamp, action type (read / label / archive / send), and subject line. You don't need this log to be verbose — just enough to audit what the agent did yesterday if something surfaces today. A simple append-only text file works perfectly.

5. Periodic Scope Audits

Every 30 days, visit your Google and Microsoft app permissions pages and verify the scopes you granted are still the minimum necessary. Agent workflows evolve — you may have added a scope for a one-off task and forgotten to remove it.

If you're running OpenClaw on a local Mac Mini M4 — which I'd strongly recommend for any persistent automation that handles sensitive data — see our guide on OpenClaw on Raspberry Pi vs Mac Mini: Which Should You Choose for hardware-level isolation options.

Frequently Asked Questions