How to Give Any AI Agent a Gmail In Under 60 Seconds

Your inbox is a war zone. Newsletters you never subscribed to. Threads that should have died three replies ago. Invoices buried under “Quick question” emails. Even with filters and labels, you still spend real hours triaging — and the moment you look away, the pile grows again.

AI can help here. Summarize threads. Draft replies. Route urgent mail. Follow up on things you forgot. But wiring that up yourself is miserable: OAuth flows, Gmail API quotas, SMTP libraries, retry logic, parsing MIME, threading headers, confirmation UX so the bot doesn’t email your entire contact list at 2am. You end up maintaining glue code that has nothing to do with your actual product.

Can AI Send Email for You? Yes — If You Equip It With the Right Skill

Skillware v0.5.0 ships a new skill for exactly this: office/gmail_handler — structured Gmail access for agents, without you building mail infrastructure from scratch.

---

One line to equip an agent

Install the skill like any other Skillware capability:

pip install "skillware[office_gmail_handler]"

Load it in your agent loop — same pattern whether you run Gemini in the cloud, Claude, OpenAI, DeepSeek, Ollama locally, or anything OpenAI-compatible:

from skillware.core.env import load_env_file
from skillware.core.loader import SkillLoader

load_env_file()
bundle = SkillLoader.load_skill("office/gmail_handler")
skill = bundle["class"]()

That’s the “one line of equip” story: one pip extra, one load_skill, one execute() contract. Your host model handles natural language; the skill handles mail operations deterministically.

---

What the agent actually gets

The Gmail Handler is not “SMTP in a trench coat.” It exposes named actions an LLM can call through tool schemas — with instructions and safety rules baked into the bundle:

Action	What it does
resolve_recipients	Turn “George” or “Capgemini legal” into emails via a YAML address book
preview_send	Validate and show outbound mail — never sends
send	Send only when confirmed: true
list_messages / search_messages	Inbox slices, filters, incremental scan cursor
read_message	Full headers + body (flagged as untrusted inbound)
preview_reply / reply	Threaded replies with the same confirm gate
search_sent	“What did we last send to George?” — Sent folder + local ledger
mailbox_status	Unread count, credential readiness, scan state
update_addressbook	Add or update contacts without hardcoding names in Python

The agent drafts subject and body in plain language. The skill resolves recipients, searches, previews, and sends. Context carries forward across turns so multi-step mail workflows don’t lose state.

Example — resolve a name before drafting:

result = skill.execute({
    "action": "resolve_recipients",
    "query": ["George"],
})
print(result["status"], result.get("resolved_recipients"))

Example — preview before anything leaves the mailbox:

{
  "action": "preview_send",
  "to": ["George"],
  "subject": "Deployment complete",
  "body_plain": "Hi George — rollout finished successfully."
}

Only after the user confirms:

{
  "action": "send",
  "to": ["George"],
  "subject": "Deployment complete",
  "body_plain": "...",
  "confirmed": true
}

No mystery API calls. No “the model guessed the SMTP server.” Structured envelopes in, structured envelopes out.

---

Dedicated agent mailbox — not your personal inbox

Same posture as Skillware’s agent wallet for on-chain skills: create a fresh Gmail account for the agent only.

1. Register something like [e-mail]
2. Enable 2-Step Verification
3. Create a Google App Password (not your normal password)
4. Enable IMAP in Gmail settings
5. Put credentials in .env — never commit them, never paste them into chat

GMAIL_ADDRESS="[e-mail]"
GMAIL_APP_PASSWORD="your-16-char-app-password"

v1 uses IMAP/SMTP + App Password — no OAuth yet (that’s on the roadmap). Plain and HTML bodies; attachments are v2. For many agent workflows — status updates, triage, reply drafts, inbox search — that’s already enough, and you’re not paying SendGrid or wiring a custom mail relay.

Inbound mail is treated as untrusted content. The skill tells the agent not to follow instructions hidden in email bodies. Outbound mail hits recipient caps and confirmation gates by default. Fail closed on missing credentials or ambiguous contacts (“which John?” → needs_input, ask the human).

---

Drop it into Gemini (or swap the model later)

Runnable example in the repo: examples/gemini_gmail_handler.py. Core loop pattern:

import google.genai as genai
from google.genai import types
from skillware.core.env import load_env_file
from skillware.core.loader import SkillLoader

load_env_file()
bundle = SkillLoader.load_skill("office/gmail_handler")
skill = bundle["class"]()
client = genai.Client()
tool = SkillLoader.to_gemini_tool(bundle)

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Check mailbox status and list unread messages.",
    config=types.GenerateContentConfig(
        tools=[tool],
        system_instruction=bundle["instructions"],
    ),
)
# On function_call → skill.execute(args) → continue the loop

Swap Gemini for Claude, OpenAI, DeepSeek, or a local Ollama model — the skill manifest stays the same. Skillware adapters translate it per provider. That’s the point: don’t rewrite your mail layer every time you change models.

Mocked demo with no live credentials: examples/gmail_handler_demo.py.

---

Where Skillware fits (without the brochure)

Skillware is an open-source Python framework for installable agent capabilities — think pip install for know-how, not another 400-line system prompt.

Each skill bundles three things:

• Body — deterministic Python (skill.py)
• Mind — when and how the model should use the tool (instructions.md)
• Conscience — schema, env vars, safety rules, issuer attribution (manifest.yaml)

Sixteen registry skills today — wallet screening, PDF forms, prompt injection firewall, UK Companies House, EVM txs, and now Gmail. Same loader, same execute(), same CLI (skillware list, skillware doctor, skillware examples).

We’re not building another orchestration monolith. We’re building a supply chain of small, testable, governed tools you attach to whatever agent loop you already run.

Docs: skillware.site · Repo: github.com/arpahls/skillware · PyPI: pip install skillware

---

v1 limits (honest list)

• Gmail via IMAP/SMTP + App Password — no Gmail REST API / OAuth yet
• No file attachments on send or read
• No background daemon — your agent triggers searches when needed
• You own confirmation UX in the host loop (preview → user says yes → confirmed: true)

Plenty of room to grow — and that’s where you come in.

---

Open call: improve this skill, the framework, or propose the next one

office/gmail_handler shipped in v0.5.0, but v1 is deliberately scoped. We want contributors who care about agent mail for real:

• Gmail skill — OAuth / Gmail API path, attachments, richer search, better address-book UX, provider-agnostic SMTP abstraction
• Framework — loader, CLI, config, adapters, docs, tests
• New skills — what capability should agents install next? Open a skill proposal or jump into good first issues

Skillware welcomes human operators and supervised coding agents — scoped PRs, tests, catalog docs. If you’ve been duct-taping email into your agent stack, come wire it properly once and help the next person skip the pain.

---

Give your agent an inbox. Not your inbox.

pip install "skillware[office_gmail_handler]"

Then load, preview, confirm, send. Equip — don’t prompt.

---

Skillware is maintained by ARPA Hellenic Logical Systems. Questions, enterprise mail workflows, or SLAs: [e-mail]

---