{"slug": "email-tools-for-claude-tool-use-with-an-agent-mailbox", "title": "Email Tools for Claude: Tool Use With an Agent Mailbox", "summary": "Nylas has introduced Agent Accounts, a hosted mailbox for AI agents that can be created with a single CLI command. A developer demonstrated how Claude can operate a real mailbox using three tool definitions and about forty lines of glue code, bypassing the complexity of OAuth and provider-specific APIs. The approach uses the Nylas CLI to handle authentication and provider differences, enabling agents to read, search, and send emails autonomously.", "body_md": "Claude can operate a real mailbox with three tool definitions and about forty lines of glue code.\n\n```\ntools = [\n    {\n        \"name\": \"read_emails\",\n        \"description\": \"List recent emails from the agent's inbox. Returns JSON.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"limit\": {\"type\": \"integer\", \"default\": 10},\n                \"unread_only\": {\"type\": \"boolean\", \"default\": False},\n            },\n        },\n    },\n    {\n        \"name\": \"search_emails\",\n        \"description\": \"Search the agent's mailbox for messages matching a query.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\"query\": {\"type\": \"string\"}},\n            \"required\": [\"query\"],\n        },\n    },\n    {\n        \"name\": \"send_email\",\n        \"description\": \"Send an email from the agent's own address.\",\n        \"input_schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"to\": {\"type\": \"string\"},\n                \"subject\": {\"type\": \"string\"},\n                \"body\": {\"type\": \"string\"},\n            },\n            \"required\": [\"to\", \"subject\", \"body\"],\n        },\n    },\n]\n```\n\nThe interesting part isn't the schemas — it's what backs them. Instead of pointing these tools at a human's Gmail over OAuth, you can point them at a [Nylas Agent Account](https://developer.nylas.com/docs/v3/agent-accounts/): a hosted mailbox the agent owns outright, created with one command on a registered domain:\n\n```\nnylas agent account create agent@yourdomain.com\n```\n\nAgent Accounts are in beta, but they behave like any other grant, which means the same CLI commands and API endpoints work unchanged.\n\nIf you hand-roll Gmail OAuth, you're writing roughly 300 lines of token plumbing before the agent does anything useful. Add Microsoft Graph and you're at 600. Add IMAP fallback and you're past 1,000. The [LLM agent with tools recipe](https://developer.nylas.com/docs/cookbook/cli/llm-agent-with-tools/) takes a different route: shell out to the `nylas`\n\nCLI and let it handle auth, refresh, and provider differences. The implementations are short:\n\n``` php\nimport json, subprocess\n\ndef _run(cmd: list[str]) -> str:\n    out = subprocess.run(cmd, capture_output=True, text=True, timeout=30)\n    return out.stdout if out.returncode == 0 else f\"Error: {out.stderr}\"\n\ndef read_emails(limit: int = 10, unread_only: bool = False) -> str:\n    cmd = [\"nylas\", \"email\", \"list\", \"--limit\", str(limit), \"--json\"]\n    if unread_only:\n        cmd.append(\"--unread\")\n    return _run(cmd)\n\ndef search_emails(query: str) -> str:\n    return _run([\"nylas\", \"email\", \"search\", query, \"--limit\", \"5\", \"--json\"])\n\ndef send_email(to: str, subject: str, body: str) -> str:\n    return _run([\"nylas\", \"email\", \"send\", \"--to\", to, \"--subject\", subject,\n                 \"--body\", body, \"--yes\", \"--json\"])\n```\n\nTwo flags matter more than they look. `--yes`\n\nskips the interactive \"send this?\" confirmation — without it, the send command blocks forever waiting for a keypress no agent will ever make. `--json`\n\nreturns structured output the model can actually parse instead of human-formatted text.\n\nAnthropic's tool-use flow is a loop: call the model, execute any `tool_use`\n\nblocks, feed results back, repeat until the model answers in plain text.\n\n``` python\nimport anthropic\n\nclient = anthropic.Anthropic()\nDISPATCH = {\"read_emails\": read_emails, \"search_emails\": search_emails,\n            \"send_email\": send_email}\n\nmessages = [{\"role\": \"user\", \"content\": \"Did anyone reply about the contract?\"}]\nwhile True:\n    resp = client.messages.create(\n        model=\"claude-sonnet-4-5\", max_tokens=1024,\n        tools=tools, messages=messages,\n    )\n    messages.append({\"role\": \"assistant\", \"content\": resp.content})\n    if resp.stop_reason != \"tool_use\":\n        print(resp.content[0].text)\n        break\n    results = [\n        {\"type\": \"tool_result\", \"tool_use_id\": block.id,\n         \"content\": DISPATCH[block.name](**block.input)}\n        for block in resp.content if block.type == \"tool_use\"\n    ]\n    messages.append({\"role\": \"user\", \"content\": results})\n```\n\nClaude may issue several tool calls before producing a final answer — search first, read a specific message, then draft a reply. The loop shape doesn't care.\n\nGive the loop a real task and the trace is more interesting than the code. For \"Did anyone reply about the contract?\", a typical run goes:\n\n`tool_use`\n\nblock: `search_emails`\n\nwith `{\"query\": \"contract\"}`\n\n.`read_emails`\n\nwith `{\"limit\": 10}`\n\nto pull recent messages with full context.`stop_reason`\n\ncomes back as `end_turn`\n\nand Claude answers in plain text: who replied, when, and what they said.No step in that sequence was scripted. The model decided to search before reading, and decided two tool calls were enough. That's the whole appeal of tool use over a hardcoded pipeline — and also why the guardrails below matter.\n\n`read_emails`\n\nand `search_emails`\n\nare harmless. `send_email`\n\nis not, so it deserves three layers of restraint:\n\n`timeout=30`\n\non every `subprocess.run`\n\ncall isn't decoration. A CLI command waiting on a prompt or a slow network would otherwise hang the loop forever — exactly the failure mode `--yes`\n\nexists to prevent, caught a second time.`--api-key`\n\nexplicitly so one tenant's loop can never touch another tenant's mailbox.`nylas email list --limit 100`\n\nproduces a wall of JSON that'll eat your context window. The cookbook's advice: cap `limit`\n\naggressively in the schema itself — the default of 10 is deliberate, and 5 is a reasonable floor for list calls. Let error strings through too. Subprocess failures come back as stderr text, and the model is surprisingly good at deciding what to do with \"grant expired\" versus \"rate limited.\"\n\nOne more operational note: the CLI acts on whichever grant is currently active in `nylas auth list`\n\n. An Agent Account shows up there with `Provider: Nylas`\n\n, so after creating one, switch to it before starting the loop — otherwise your agent cheerfully sends from your personal address.\n\nBacking these tools with the agent's own address changes the safety story. Replies land in an inbox your application controls. There's no human whose sent folder fills with machine-written mail, and no OAuth consent that breaks when that human leaves the company. The mailbox sends, receives, and threads like any normal account.\n\nThere are three ways to wire Claude to this mailbox, and they suit different runtimes:\n\n| Route | Best for | What it takes |\n|---|---|---|\n| Subprocess + CLI (this post) | Custom Python loops you fully control | Three wrapper functions, ~40 lines |\n| MCP | Hosts that already speak MCP, like Claude Code |\n`nylas mcp install --assistant claude-code` — registers 16 email, calendar, and contacts tools, no wrappers |\n| SDK / raw API | Production services |\n`pip install nylas` , then call `{base_url}/v3/grants/{grant_id}/{resource}` with a Bearer API key |\n\nThe SDK route trades the CLI's convenience for explicitness: every call carries the `grant_id`\n\n, errors come back as structured JSON with an `error.type`\n\nfield (`unauthorized`\n\n, `rate_limit_error`\n\n, `invalid_request_error`\n\n), and nothing depends on local CLI state. The [autonomous agents quickstart](https://developer.nylas.com/docs/v3/getting-started/cli-for-agents/) covers the CLI and MCP routes, and the [coding agents guide](https://developer.nylas.com/docs/v3/getting-started/coding-agents/) covers the SDK path if you'd rather call the API directly.\n\nTry giving the loop a task that requires multiple turns — \"find the latest invoice email and forward a summary to accounting\" — and watch which tools Claude chains together. What's the first tool you'd add beyond these three?", "url": "https://wpnews.pro/news/email-tools-for-claude-tool-use-with-an-agent-mailbox", "canonical_source": "https://dev.to/qasim157/email-tools-for-claude-tool-use-with-an-agent-mailbox-4ckp", "published_at": "2026-06-15 20:04:25+00:00", "updated_at": "2026-06-15 20:32:58.960061+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "large-language-models"], "entities": ["Nylas", "Claude", "Anthropic", "Agent Accounts", "Gmail", "Microsoft Graph", "IMAP"], "alternates": {"html": "https://wpnews.pro/news/email-tools-for-claude-tool-use-with-an-agent-mailbox", "markdown": "https://wpnews.pro/news/email-tools-for-claude-tool-use-with-an-agent-mailbox.md", "text": "https://wpnews.pro/news/email-tools-for-claude-tool-use-with-an-agent-mailbox.txt", "jsonld": "https://wpnews.pro/news/email-tools-for-claude-tool-use-with-an-agent-mailbox.jsonld"}}