nanoclaw email integration: how to give your agent a real inbox
A practical guide to NanoClaw email integration using Gmail, IMAP/SMTP, and Resend. Learn the setup steps, trade-offs, and what happens when your container goes offline.
NanoClaw ships with a skills-based architecture that lets you bolt on integrations one at a time. Email is one of those skills. Run /add-gmail inside your agent session and you've got inbox access. On paper, it's simple.
In practice, NanoClaw email integration raises a set of questions that the official docs don't fully answer. What happens to queued messages when your container restarts? How do you handle multiple accounts? What about deliverability when you're sending at any real volume? I spent a week testing NanoClaw's email capabilities across Gmail OAuth, raw IMAP/SMTP, and Resend to figure out where it works well, where it breaks down, and where you might want a dedicated layer underneath.
What is NanoClaw?#
NanoClaw is a lightweight, self-hosted AI agent that runs inside containers. It connects to WhatsApp, Telegram, Slack, Discord, Gmail, and about a dozen other messaging platforms. Built on Anthropic's Claude Agent SDK, it uses Claude Code as its default LLM and supports drop-in alternatives like OpenAI Codex, DeepSeek, and local models through OpenRouter.
The key difference from OpenClaw: NanoClaw runs in isolated containers for security and takes a modular approach to integrations. Instead of bundling everything into the core, you install "skills" on demand. Email is one such skill. NanoClaw is free and open source, hosted on GitHub under the qwibitai organization.
How to add email to NanoClaw (step-by-step)#
- Fork and deploy the NanoClaw repo following the container setup guide
- Run
/add-gmailor/add-emailin your agent session to install the email skill - Authenticate with your provider credentials (OAuth for Gmail, app password for IMAP/SMTP)
- Choose between "tool" mode (agent uses email on demand) or "full channel" mode (agent monitors and responds automatically)
- Verify by asking your agent to summarize your inbox
That's the quick version. Each step has its own set of decisions, so let's break them down.
Gmail via OAuth#
The /add-gmail skill connects NanoClaw to a Gmail account using OAuth tokens. Your agent can read, draft, and send messages. Gmail OAuth is the path of least resistance if you're already in Google's ecosystem. The trade-off: OAuth tokens expire, and NanoClaw doesn't currently handle token refresh in a way that survives container restarts gracefully. If your container goes down and comes back up, you may need to re-authenticate.
Google also limits what OAuth apps can do before verification. If you're building something for more than personal use, you'll need to go through Google's OAuth consent screen review process. That's a multi-week timeline with manual review steps.
IMAP/SMTP#
For non-Gmail providers, NanoClaw supports raw IMAP and SMTP connections. You provide a server address, port, username, and password (or app-specific password). This works with Outlook, Fastmail, Zoho, or any provider that supports standard protocols.
The catch: NanoClaw polls for new messages using IMAP. There's no push notification, no webhook, no event-driven trigger. Your agent checks the inbox on an interval. For a personal assistant that checks email every few minutes, that's fine. For an agent that needs to react to incoming mail in seconds, polling introduces latency that you can't fully eliminate without modifying NanoClaw's core.
Resend as a provider#
NanoClaw also supports Resend for outbound email. Resend gives you a clean sending API with good deliverability defaults. But it's send-only. You still need an IMAP connection or Gmail OAuth for receiving. This means running two integrations in parallel for full bidirectional email, which adds complexity to your container configuration.
Tool mode vs. full channel mode#
This is one of the more interesting design decisions in NanoClaw's email integration. You can configure email as either a "tool" or a "full channel."
Tool mode means your agent can send and read email when explicitly asked. "Send an email to the team" or "check my inbox" triggers the email skill. The agent doesn't monitor the inbox passively.
Full channel mode treats email like WhatsApp or Telegram. Incoming emails become messages in the agent's conversation stream. The agent can auto-draft replies, summarize threads, and act on incoming mail without being asked. This is powerful for workflows like customer support triage, order confirmation monitoring, or lead response.
The downside of full channel mode is volume. A busy inbox generates dozens or hundreds of messages per day. Each one consumes LLM tokens. Without careful filtering, your agent will burn through API credits reading newsletters and promotional emails that don't need a response.
Where NanoClaw email integration gets tricky#
NanoClaw handles the basics well. For a single personal inbox connected to a personal agent, the setup works. But a few gaps emerge as you push further.
Container restarts lose state. NanoClaw runs in Docker containers. If the container goes down (crash, host reboot, scaling event), any in-memory email state disappears. Pending drafts, partially processed threads, and OAuth sessions may not survive the restart. The docs don't describe a store-and-forward mechanism for email that persists outside the container lifecycle.
Single account assumption. All of NanoClaw's email documentation assumes one inbox connected to one agent. If you need multiple email accounts, team routing, or multi-tenant setups, you're building that yourself. There's no built-in abstraction for "this agent handles support@, that agent handles billing@."
Deliverability is on you. NanoClaw doesn't manage DNS records, SPF alignment, DKIM signing, or domain warm-up. It connects to your existing email provider and uses whatever reputation that provider gives you. If you're sending through a personal Gmail account, you inherit Gmail's sending limits (about 500 per day for consumer accounts, 2,000 for Workspace). If you're using SMTP with your own domain, you need to configure authentication records yourself and monitor your sender reputation.
No webhook-based inbound. Inbound email in NanoClaw is always poll-based. The agent checks the inbox at intervals. For time-sensitive workflows (password reset codes, verification emails, real-time alerts), polling adds seconds or minutes of delay. There's no way to configure a webhook endpoint that triggers the agent immediately when a new email lands.
Credential management is manual. You store email credentials (OAuth tokens, app passwords, SMTP passwords) in NanoClaw's configuration. Rotating those credentials means re-authenticating manually. For a personal setup, that's a minor annoyance. For a team managing multiple agents, it becomes operational overhead.
When a dedicated email layer makes sense#
If your agent sends fewer than 50 emails a day from a single account and doesn't need instant inbound response, NanoClaw's built-in email skills will probably work fine. It's a reasonable choice for personal automation.
The calculus changes when you need any of: multiple inboxes, instant inbound delivery, sending at volume without managing DNS records, or email that keeps working when your container is down. Those requirements point toward a dedicated email infrastructure layer that sits underneath NanoClaw rather than inside it.
LobsterMail was built for exactly this kind of setup. Your agent provisions its own inbox with a single SDK call, sends and receives without managing credentials, and gets built-in protection against prompt injection attacks in email content. The inbox persists independently of your container's lifecycle, so email keeps arriving even if NanoClaw restarts.
For NanoClaw users who want email reliability without managing the plumbing, connecting to a dedicated email API removes the polling limitations, credential rotation, and deliverability concerns that come with the built-in skills. Your NanoClaw agent calls the API, gets an inbox, and focuses on what it's actually good at.
Frequently asked questions
How do I add Gmail to NanoClaw using the /add-gmail skill?
Run /add-gmail in your NanoClaw agent session. The skill will walk you through OAuth authentication with your Google account. Once connected, your agent can read, draft, and send emails from that Gmail address.
What is the difference between using email as a 'tool' vs. a 'full channel' in NanoClaw?
Tool mode lets your agent send and read email only when you explicitly ask. Full channel mode treats email like a messaging app, where incoming emails appear in the agent's conversation stream and can trigger automatic responses.
Does NanoClaw support IMAP and SMTP, or only Gmail OAuth?
NanoClaw supports both. Gmail OAuth is the easiest path, but you can connect any email provider that supports standard IMAP/SMTP using the /add-email skill with server credentials.
Can NanoClaw automatically draft and send replies to incoming emails?
Yes, when email is configured in full channel mode. The agent monitors your inbox and can auto-draft or auto-send replies. In tool mode, the agent only acts on email when you ask it to.
What happens to pending emails if my NanoClaw container restarts or goes offline?
Emails in your provider's inbox (Gmail, IMAP server) remain safe. But any in-memory state inside NanoClaw, like partially processed threads or pending drafts, may be lost. NanoClaw doesn't currently have a store-and-forward mechanism that persists across container restarts.
Does NanoClaw support multiple email accounts simultaneously?
Not natively. The current documentation and architecture assume a single inbox per agent. Running multiple email accounts requires manual configuration or running separate NanoClaw instances.
Can I use Resend as the email provider instead of Gmail in NanoClaw?
Yes, for outbound email. Resend gives you a clean sending API. But Resend is send-only, so you'll still need Gmail or an IMAP connection for receiving messages.
How does NanoClaw's skills-based email architecture compare to OpenClaw's bundled integrations?
NanoClaw installs email as an optional skill on demand, keeping the core lightweight. OpenClaw bundles integrations into the core codebase, which gives you more out of the box but makes the system heavier. NanoClaw's approach is more modular; OpenClaw's is more batteries-included.
Is NanoClaw free and open source?
Yes. NanoClaw is fully open source and available on GitHub under the qwibitai organization. You self-host it in Docker containers.
How do I revoke NanoClaw's access to my Gmail account?
Go to your Google Account security settings, find "Third-party apps with account access," locate NanoClaw's OAuth entry, and remove it. This immediately revokes the OAuth token.
Can NanoClaw trigger automated agent workflows from incoming email?
In full channel mode, incoming emails enter the agent's conversation stream and can trigger responses. But there's no webhook-based trigger for instant reactions. NanoClaw uses polling, so there's always some delay between email arrival and agent response.
Is there a rate limit on how many emails NanoClaw can send per day?
NanoClaw itself doesn't impose rate limits, but your email provider does. Gmail consumer accounts allow about 500 sends per day. Google Workspace allows around 2,000. SMTP providers and Resend have their own limits.
How does NanoClaw handle email attachments?
NanoClaw can read and send attachments through its email skills. The handling depends on your provider connection. Large attachments may consume significant memory inside the container, so keep an eye on resource usage.
What are the main limitations of NanoClaw email compared to a dedicated email API?
The biggest gaps are polling-based inbound (no instant delivery), manual credential management, no built-in deliverability tooling (SPF, DKIM, domain warm-up), single-account assumptions, and loss of in-memory state during container restarts. A dedicated email API like LobsterMail handles all of these at the infrastructure level.
