Build an agent that sorts
your Gmail inbox
and writes you a morning briefing.

— Prep

What you need before you start.

Before you dive into the tutorial, make sure you have these four things.

• A Mac (Windows works too, but the cron commands are different — I cover the Mac case here).
• A Gmail account, personal or work.
• A Claude Pro subscription at €20 a month (claude.ai). It lets you use Claude Code without pay-per-use billing for reasonable volumes.
• Forty-five minutes to yourself, uninterrupted. If you break in the middle of an OAuth step (the standard procedure for authorizing an app to access your Google account without handing over your password), you'll have to start over.

If you've never opened a terminal in your life, this tutorial is still doable. You're going to copy and paste five commands. But take your time on each one.

— Step 1

Step 1 — Install Claude Code.

Open the Terminal app on your Mac (type " Terminal " in Spotlight). Official Claude Code & Agent SDK docs.

Paste this command and press Enter :

curl -fsSL https://claude.ai/install.sh | bash

Wait for the installation to finish. This script downloads Claude Code and makes it available everywhere on your Mac.

Then launch Claude Code for the first time :

claude

You'll be asked to sign in with your Claude.ai account. Follow the link, authorize the connection in your browser, come back to the terminal. You should see a prompt (the area where you type your instructions to the AI) ready to take instructions.

Type /exit to quit for now. We'll come back to it.

— Step 2

Step 2 — Connect your Gmail.

You have two options to connect Gmail to Claude Code. One is simple, the other gives you more control.

Option A — Claude's native Gmail connector (recommended for beginners).

Head to claude.ai/settings/connectors. You'll see a list of connectors. Click " Connect " next to Gmail. Accept the Google authorization. That's it. This connector is inherited automatically in Claude Code when you sign in with the same account.

One limit to know : this connector lets you read your emails and create drafts, but not send them or label them automatically. For a sorter that gives you a summary, that's plenty.

Option B — A Gmail MCP server (to go further).

If you want the agent to be able to label and archive emails, you'll need an MCP server (a small program that bridges Claude and an external service — here, Gmail). Official Model Context Protocol spec. The cleanest one today is called shinzo-labs/gmail-mcp. Paste this command into Claude Code :

claude mcp add --transport stdio --scope user gmail -- npx -y @shinzolabs/gmail-mcp

This option asks you to create a project on the Google Cloud Console and download an OAuth key (an authentication file provided by Google that proves to Gmail your agent is allowed to access your inbox). Official Gmail API docs. If it's your first time, start with option A. You can switch later.

Note: I'll redo the screenshots of the Google OAuth flow (consent screen, Gmail scopes, key generation) in the next update — for now, follow the step-by-step screens in the official Gmail API quickstart.

— Step 3

Step 3 — Write the system prompt.

This is the most important part of the tutorial. The system prompt (the background instructions the agent keeps in mind at every turn) frames everything else. An agent without clear instructions goes off in every direction.

In your terminal, create a folder for your agent :

mkdir -p ~/gmail-agent && cd ~/gmail-agent

Then create a file named CLAUDE.md with this exact content (you can copy and paste) :

# Gmail agent — Morning briefing

## Role
You are my email assistant. You sort my Gmail inbox and give me
an actionable briefing I can read in two minutes. You are factual,
brief, direct. You don't write novels.

## Context
- I get about 80 emails a day (clients, prospects,
  newsletters, tool notifications, disguised spam).
- I want to know in thirty seconds what matters today.
- I approve the actions myself: you propose drafts,
  never automatic sending.

## Allowed tools
- Read emails from the last 24 hours.
- Create reply drafts.
- Label emails (if advanced connector).

Forbidden: sending an email, deleting an email, emptying folders.

## Limits
- No more than 50 emails analyzed per run.
- No emails older than three days.
- Never the Spam, Trash or Drafts folders.
- If you're unsure of a category, put "Sort manually."

## Categorization
Every unread email goes into ONE of the six categories below:

1. URGENT — action within 24 h (unhappy client, unpaid invoice,
   deadline, personal emergency).
2. IMPORTANT — reply expected this week (meeting to confirm,
   decision to make).
3. PROSPECT — inbound sales message, request for a quote.
4. NEWSLETTER — to skim, never in the day's top 3.
5. AUTO — tool notifications (GitHub, Stripe, Calendly).
6. DISGUISED SPAM — unsolicited pitch, annoying cold email.

## Output format
Reply in exactly this format:

### Top 3 of the day
1. [Sender] — [subject in 10 words] — Action: [what to do]
2. ...
3. ...

### Summary by category
- Urgent: X emails
- Important: X emails
- Prospect: X emails (drafts created: Y)
- Newsletter: X emails
- Auto: X emails
- To sort: X emails

### Drafts prepared
- Re: [subject] — tone chosen

### Odd things spotted
[Suspicious pitches, possible phishing]

## Top 3 criterion
The top 3 are the three emails where not replying today
has a real business cost. Not the most recent, not the longest.
The most expensive to ignore.

This prompt defines six categories and enforces a precise output format. You can tweak it for your line of work — I give you some variants at the end of the tutorial.

— Step 4

Step 4 — Create your slash command.

A slash command (a custom shortcut like /my-command) lets you launch your agent with a single command instead of retyping the instructions every time.

In your folder, create a file at .claude/commands/tri-matinal.md with this content :

---
description: Gmail sort + briefing of the day
---
Run the following morning sort using the protocol defined in CLAUDE.md.

1. Fetch the unread emails from the last 24 h (max 50).
2. Classify each email into the six categories.
3. For the PROSPECT category, create a short reply draft.
4. Return the briefing in the enforced format.

Don't ask any questions. Execute, then display the report.

You can now launch the sort by simply typing /tri-matinal in Claude Code.

— Step 5

Step 5 — First test.

In your terminal, from the ~/gmail-agent folder, launch Claude Code :

claude

Type :

/tri-matinal

The agent will read your emails, apply the categories, prepare the drafts, and hand you the briefing. The first time, it takes thirty to sixty seconds.

What you should see :

### Top 3 of the day
1. Jean Dupont (Client Acme) — follow-up on Q3 proposal —
   Action: confirm a call slot
2. Accounting firm — request for year-end documents —
   Action: send 2026 invoices
3. Laura Marchand (prospect) — request for a quote —
   Action: review draft and send

### Summary by category
- Urgent: 3 emails
- Important: 5 emails
- Prospect: 2 emails (drafts created: 2)
- Newsletter: 38 emails
- Auto: 24 emails
- To sort: 3 emails

If you get this format, your agent works. If you get something else, check that you copied the whole CLAUDE.md and that the Gmail connector is active.

— Step 6

Step 6 — Automate it every morning at 7 a.m.

You now have an agent that works on demand. All that's left is to make it run automatically while you sleep.

Three options, from simplest to most involved.

Option 1 — Claude Code routines.

In Claude Code, type :

/schedule "every day at 07:00" "/tri-matinal"

This is the simplest option. The routine runs in the Claude cloud; your Mac doesn't need to be on.

Option 2 — launchd on macOS (more control).

You create a scheduling file (the macOS equivalent of a cron — a scheduler that runs tasks at fixed times) that triggers Claude Code every morning. This requires your Mac to be on at 7 a.m. The steps are more technical — I document them in the downloadable pack (see the end of the article).

Option 3 — Zapier / Make.

You can also orchestrate it from Zapier or Make.com, which triggers Claude Code remotely. Handy if you want to get the summary by SMS or WhatsApp.

— The result

What it changes after a week.

Here's the plausible scenario for an entrepreneur who gets 80 emails a day :

	Before the agent	After the agent
Morning sorting time	1 h 45	15 min reading the summary
Emails read in full	15 to 20	3 (the day's top 3)
Important emails forgotten	3 to 4 a week	Very rare
Mental load	High	Low

That's roughly 33 hours recovered a month for a cost of about €5 a month in API usage (billing per request, as opposed to a flat subscription). The rate is Haiku 4.5 at $1 per million tokens (the units the model counts for billing, ~3-4 characters each) in, and $5 out — see the Anthropic pricing. You can check the usage in your account.

— The pitfalls

The three pitfalls to avoid.

Pitfall 1 — Giving the agent too many permissions.

Never turn on automatic email sending until you have a month of use behind you. Drafts are enough. An agent that " accidentally " sends an email to a client costs you more than two years of Claude Pro.

Pitfall 2 — A prompt that's too vague.

If you replace " You are my email assistant " with " Help me with my emails ", the agent will go off in every direction. The system prompt in section 3 is precise on purpose : role, context, tools, limits, categories, output format. Stick to that structure.

Pitfall 3 — Forgetting to check the categories during the first week.

The agent will make mistakes. Newsletters in " Urgent ", real urgents in " To sort ". For seven days, open the categories and adjust your prompt by adding rules : " Emails from this address are always urgent ", " Substack digests are never urgent ". After a week, the agent is calibrated.

— Customization

By-profession variants (replace the base prompt).

If you're a coach or trainer, replace the " Categorization " section with :

1. ACTIVE CLIENT — any email from a client on an engagement (list in clients.md).
2. PROSPECT — discovery request, sales call.
3. MEETING — confirmation, cancellation, reschedule.
4. NEWSLETTER — to skim, never a priority.
5. AUTO — Calendly, Zoom, Stripe notifications.

If you're an e-commerce seller, prioritize customer support :

1. URGENT SUPPORT — complaint, return, lost delivery, negative review.
2. SUPPLIER — orders, stock alerts.
3. FINANCE — Stripe, bank, invoices.
4. PROSPECT — B2B requests.
5. AUTO — platform notifications.
6. ADS — Meta/Google Ads rejections only.

If you're a B2B consultant, prioritize billing :

1. FINANCE — unpaid invoices, reminders, payments received.
2. LEADS — quote requests, mentions of your expertise.
3. CLIENT ON ENGAGEMENT — any active client.
4. MEETING — calendar.
5. NEWSLETTER — industry digest.

— Your turn

And you, did you install it ?

If you followed this tutorial all the way through, you now have an agent that runs every morning and saves you about an hour and a half a day.

Three things I'd love to know :

1. How long did the full setup take you ?
2. Which category did the agent struggle with at first ?
3. Which prompt variant did you pick ?

Reply to this email with your setup. I read everything, I reply.

I can be wrong. Gmail MCPs move fast and some of the GitHub repos used in this tutorial may become outdated. If a command stops working, write to me and I'll update the tutorial.

To go further with Claude Code agents: the agent that analyzes your PDF contracts tutorial (same logic, legal topic), the Hermes Agent step by step (a more advanced multi-tool agent) and the general guide to AI agents to understand how it all works.

— FAQ

Gmail agent FAQ.

What do you need to build an agent for Gmail with Claude Code?

Four things: a Mac (Windows is fine but the scheduling commands are different), a personal or work Gmail account, a Claude Pro subscription at €20/month, and 45 minutes uninterrupted. No need to know how to code — just copy and paste five commands.

How much does it cost per month?

About €5/month in API usage from Anthropic for 80 emails/day with Haiku 4.5 ($1 per million input tokens, $5 per million output tokens). With Claude Pro at €20, reasonable volumes are already included. You can track your real usage in your Anthropic dashboard.

Do you need an MCP server to connect Gmail?

No, not to get started. The native Gmail connector (claude.ai/settings/connectors) is enough to read emails and create drafts. You only need an MCP server (e.g. shinzo-labs/gmail-mcp) if you want to label or archive automatically — and for that you'll have to go through a Google Cloud project with an OAuth key.

How do you avoid hallucinations in the sorting?

Three levers: a precise system prompt with named categories (role, context, tools, limits, format), an enforced output format the agent has to follow, and manual calibration during the first week, where you fix the misfiled emails by adding rules like "emails from this address are always urgent."

Can the agent send emails and risk spamming people?

No, and that's on purpose. The system prompt explicitly forbids automatic sending: the agent creates drafts that you approve yourself. Hard rule: never grant sending permission before a month of use. One email sent to a client by mistake costs more than two years of Claude Pro.

Does it work with Outlook, Yahoo or Workspace?

Claude's native connector covers Gmail (personal and Workspace). For Outlook or Yahoo, you need a third-party MCP server or an orchestrator like Make.com or Zapier that pushes the emails to Claude. This tutorial targets Gmail only — the prompt logic stays the same on other clients.

How many emails a day can it handle?

The system prompt caps at 50 emails analyzed per run to stay fast and readable. You can push it to 100-150 if needed; the cost scales proportionally (~$0.05 to $0.10 per 100 emails with Haiku 4.5). Beyond that, you're better off filtering upstream with a Gmail rule that excludes known newsletters.

Are my emails used to train Claude?

No. By default, Anthropic doesn't use Claude Pro, API or Claude Code data to train its models. For Enterprise accounts, the Zero Data Retention (ZDR) option guarantees nothing is stored after processing. For personal or freelance use, the default setting is more than enough.

Can you manage without Claude Pro?

Yes, by going straight through the Anthropic API on pay-as-you-go. You install Claude Code, create an API key, and pay per use. For 80 emails/day with Haiku 4.5, you stay under €5/month — cheaper than Claude Pro, but without the chat interface on claude.ai.

How do you automate the sorting every morning at 7 a.m.?

Three options, from simplest to most involved. Option 1: Claude Code's /schedule, which runs in the Anthropic cloud (Mac can be off). Option 2: macOS launchd (the cron equivalent), which requires the Mac to be on. Option 3: Make.com or Zapier, which trigger Claude Code remotely and deliver the summary by SMS or WhatsApp.