how to manage your agent's email inbox from the command line

Raf Camlet's viral post on building a Gmail CLI for Claude Code kicked off a wave of developers piping their inbox through the terminal. The idea is compelling: skip the browser, let your agent triage email, summarize newsletters, archive thousands of messages in seconds. The post got tens of thousands of reads and a flood of GitHub stars. But buried in the setup instructions are six OAuth scopes, a Google Cloud project, a service account JSON file, and a consent screen that expires every seven days in test mode.

That's a lot of infrastructure for "let the agent read my email."

CLI tools for managing agent email have come a long way since the days of mutt and alpine. In 2026, the real question isn't whether you can manage an agent's email from the command line. It's whether you should be managing your personal Gmail from a CLI, or giving your agent its own inbox that it controls from the start.

This article walks through both approaches, the tradeoffs of each, and why agent-first email infrastructure is eating the DIY CLI approach for most use cases.

The Gmail CLI approach (and where it breaks down)#

The Camlet-style setup works like this: you create a Google Cloud project, enable the Gmail API, generate OAuth credentials, build a Node.js wrapper around the Gmail REST API, and expose it to your coding agent as a set of shell commands. Your agent can then run something like gmail search "from:stripe subject:invoice" and get structured output.

For personal inbox triage, this is genuinely useful. You can have Claude Code archive 3,000 unread newsletters in a single session. You can build custom filters that are smarter than Gmail's built-in rules. You can pipe email content into other tools.

But the moment you try to use this pattern for an autonomous agent (one that needs its own email identity, not yours), the problems stack up fast:

OAuth tokens expire. Google's OAuth tokens have a 7-day expiry for apps in "testing" mode. Publishing the app requires a review process that takes weeks. Your agent works perfectly on Monday and silently fails on the following Tuesday because the refresh token died.

Scope creep is a security risk. Giving an agent gmail.modify scope means it can delete your emails, not just the agent's messages. There's no way to restrict a Gmail CLI to "only this agent's correspondence" because Gmail doesn't have that concept. It's your whole inbox or nothing.

You're sharing an identity. When your agent sends email through your Gmail, it sends as you. Recipients see your name, your address, your reply history. If the agent makes a mistake (sends a duplicate, replies to the wrong thread, uses a weird tone), it looks like you made that mistake.

Rate limits hit different for automation. Gmail's API allows roughly 250 quota units per second per user. A single messages.list call costs 5 units. An agent that polls every 30 seconds, processes attachments, and sends replies can burn through that quota in minutes, especially during batch operations.

None of this means the Gmail CLI approach is bad. For your inbox, managed by you with agent assistance, it's a great tool. The problem is that developers keep reaching for it when what they actually need is agent-owned email, and those are two very different things.

What agent-owned email actually looks like#

An agent that owns its own inbox doesn't authenticate against your personal account. It provisions an address, receives mail at that address, and sends from it. No shared credentials, no token refresh dances, no risk of accidentally archiving your mortgage documents.

Here's the practical difference. With a Gmail CLI, your agent runs:

gmail send --to client@example.com --subject "Invoice" --body "Attached."

The email arrives from you@gmail.com. The recipient replies to you. The agent has to filter your entire inbox to find the response.

With agent-owned email, the agent provisions its own address and works from there:

import { LobsterMail } from '@lobsterkit/lobstermail';

const lm = await LobsterMail.create();
const inbox = await lm.createSmartInbox({ name: 'Invoice Bot' });
// inbox.address → invoice-bot@lobstermail.ai

await inbox.send({
  to: 'client@example.com',
  subject: 'Invoice #1042',
  body: 'Your invoice is attached.',
});

const replies = await inbox.receive();

The email arrives from invoice-bot@lobstermail.ai. Replies go back to that address. The agent's inbox contains only its own correspondence. No filtering needed, no scope conflicts, no OAuth.

CLI tools that actually work for agent email#

If you want command-line control over your agent's email (and you should, because GUIs are terrible for automation), here are the options that hold up in practice.

LobsterMail's MCP server#

The MCP (Model Context Protocol) server gives any compatible agent email tools without writing code. Claude Code, Cursor, Windsurf, and other MCP-compatible tools can use it directly. Your agent gets create_inbox, send_email, receive_emails, and list_inboxes as callable tools.

Setup is one line in your MCP config:

{
  "mcpServers": {
    "lobstermail": {
      "command": "npx",
      "args": ["-y", "@lobsterkit/lobstermail-mcp"]
    }
  }
}

No API keys to paste. No OAuth flow. The agent self-provisions on first use. If you're using Claude Code or Cursor, this is the fastest path from "I want my agent to have email" to "my agent has email."

If you want your agent handling email right now, grab the setup instructions here and paste them into your agent. It takes about 90 seconds.

AgentMail CLI#

AgentMail offers a CLI tool (agentmail-cli) and SDKs in Python, TypeScript, and Go. It's the other major player in agent-specific email. Their approach is similar: API-first, programmatic inbox management, built-in SPF/DKIM/DMARC. The main difference is that AgentMail requires you to sign up, grab an API key, and pass it to the CLI manually. It works, but there's a human in the loop for that first provisioning step.

MCP Agent Mail (open source)#

Jeff Dicklesworth's mcp_agent_mail is an interesting open-source project that adds a mail-like coordination layer for multi-agent workflows. It's built on FastMCP, Git, and SQLite, which means it runs locally with no external dependencies. The catch: it's designed for inter-agent messaging, not for sending and receiving real email on the internet. Think of it as internal Slack for your agents, not an inbox that can receive a Stripe webhook notification.

The DIY SMTP approach#

You can always spin up Postfix, configure DNS records, set up DKIM signing, build an IMAP interface, and write your own CLI wrapper. Some developers do this. It works. It also takes a weekend of setup, ongoing maintenance, and the kind of DNS debugging that makes you question your career choices. If you enjoy that sort of thing, more power to you. For everyone else, it's a distraction from the thing you're actually building.

Choosing the right tool for your use case#

The decision tree is simpler than it looks:

"I want my coding agent to help me manage my personal inbox." → Build a Gmail CLI. Raf's tutorial is solid. You keep full control of your own email, and the agent acts as an assistant, not an autonomous actor.

"I want my agent to have its own email address for signups, notifications, or client communication." → Use agent-first infrastructure. The agent shouldn't be borrowing your identity. It needs its own address, its own inbox, its own send reputation.

"I want multiple agents to coordinate with each other via messages." → Look at mcp_agent_mail for internal coordination, and give each externally-facing agent its own real inbox for anything that touches the outside world.

"I want CLI control over agent inboxes." → MCP is the answer. It gives your agent (and you, through the agent) full command-line-style control over inbox creation, email sending, and message retrieval. No GUI required.

The real shift happening here#

A year ago, the idea of an AI agent having its own email felt weird. Today, it feels obvious. The Gmail CLI wave proved that developers want their agents handling email. The next step is recognizing that agents shouldn't be squatting in human inboxes to do it.

The CLI isn't going away. If anything, command-line control over email is becoming more relevant as agents become the primary users. But the infrastructure underneath needs to match. An agent that can hatch its own inbox, send authenticated email, and receive replies without touching a single human credential is a fundamentally different thing than a Python script that wraps the Gmail API.

If you're building an agent that interacts with the outside world, give it the right tools. Your inbox will thank you.