Claude Code doesn't have a built-in email feature, but you can wire up automated email reports using **Claude Code hooks** combined with a shell script and any SMTP-capable tool (like `sendmail`, `msmtp`, or the SendGrid/Mailgun CLI). This is useful for developers who want session summaries, task-completion alerts, or usage digests sent to their inbox without manual effort. Setup takes under 15 minutes.

- Claude Code hooks fire on lifecycle events: `PreToolUse`, `PostToolUse`, `Stop`, and `Notification`
- The `Stop` hook is ideal for end-of-session email reports
- You can check live usage data with `/usage` inside Claude Code, or monitor it continuously via [Usagebar](/content/site-root.html)

## What are Claude Code hooks and why they matter for automation

[Claude Code hooks](/content/blog/how-to-setup-claude-code-hooks-tutorial/index.html) are shell commands you configure in `settings.json` that run automatically at specific points in the agent lifecycle. Think of them as event listeners for your AI coding sessions. When a session ends, a tool completes, or a notification fires, your hook script runs in the background.

For email reports, the most relevant hook event is **`Stop`**: it fires when Claude Code finishes a session or task sequence. You can use this to trigger a script that collects context from the session transcript, formats it, and emails it to you or your team.

## What you need before you start

- Claude Code installed and authenticated ( [Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan))
- A working email-sending tool on your system: `msmtp`, `sendmail`, `mailx`, or a CLI wrapper for SendGrid/Mailgun/AWS SES
- Basic shell scripting comfort (bash)
- Optional: [Usagebar](/content/site-root.html) for real-time usage monitoring alongside your reports

## How to set up automated email reports: step by step

### Step 1: create your email report script

Create a script at `~/.claude/scripts/email-report.sh`. This script will be called by the hook and will send the email.

```bash
#!/bin/bash
# ~/.claude/scripts/email-report.sh

RECIPIENT="you@yourdomain.com"
SUBJECT="Claude Code session report - ", $(date '+%Y-%m-%d %H:%M')
SESSION_LOG="${CLAUDE_SESSION_LOG:-No session log available}"
CURRENT_DIR="${PWD}"

BODY=$(cat <<EOF
Claude Code Session Report
==========================
Date: $(date)
Working directory: $CURRENT_DIR

Session summary:
$SESSION_LOG

---
Sent automatically by Claude Code hooks.
EOF
)

echo "$BODY" | mail -s "$SUBJECT" "$RECIPIENT"
```

Make it executable:

```bash
chmod +x ~/.claude/scripts/email-report.sh
```

### Step 2: register the hook in Claude Code settings

Open (or create) your Claude Code user settings file. According to the [hooks documentation](/content/blog/how-to-setup-claude-code-hooks-tutorial/index.html), hooks are configured in `~/.claude/settings.json` (user-level) or `.claude/settings.json` inside a project (project-level).

Add the following to your `settings.json`:

```json
{
  "hooks": {
    "Stop": [\
      {\
        "matcher": "",\
        "hooks": [\
          {\
            "type": "command",\
            "command": "~/.claude/scripts/email-report.sh"\
          }\
        ]\
      }\
    ]
  }
}
```

The empty `matcher` means the hook fires on every stop event. You can narrow this by project or command pattern if needed.

### Step 3: configure your local SMTP tool

The script uses the `mail` command. On macOS, the easiest drop-in is **msmtp** with a Gmail or SMTP relay:

```bash
# Install via Homebrew
brew install msmtp

# Create ~/.msmtprc
account default
host smtp.gmail.com
port 587
auth on
tls on
user you@gmail.com
password your-app-password
from you@gmail.com
```

For teams or CI-style setups, using the **SendGrid CLI** or **AWS SES CLI** gives you deliverability and logs without managing SMTP credentials locally.

### Step 4: test the hook manually

Before relying on it, trigger the script manually:

```bash
bash ~/.claude/scripts/email-report.sh
```

Check your inbox. If the email arrives, the hook is ready. If not, check the output of `msmtp --debug` or your mail tool's log.

### Step 5: run a Claude Code session and verify

Start a normal Claude Code session, complete a task, and end the session. The `Stop` hook fires automatically. You should receive the email within seconds of the session finishing.

You can also check your usage mid-session with the [`/usage` slash command](/content/blog/how-to-use-claude-code-slash-commands/index.html) to see how much of your token window remains before it resets.

## How to include usage data in your email report

One of the most practical additions to the report is your current Claude Code usage stats. If you use [Usagebar](/content/site-root.html) on macOS, you get real-time usage visible in your menu bar with smart alerts at 50%, 75%, and 90% of your limit. But for email reports, you can query `claude.ai/settings/usage` or structure your hook to capture the output of `/usage` as part of the session transcript.

Knowing your usage window reset time is especially valuable for preventing the 5-hour lockout that hits at the worst possible moment, like when you're finishing a PR or unblocking a teammate.

## Advanced: send reports only on specific events or projects

You don't have to send an email on every session end. Hooks support matchers so you can be selective:

- **Project-scoped hooks**: place the hook config in `.claude/settings.json` inside your repo so it only triggers in that project
- **Tool-specific hooks**: use `PostToolUse` with a matcher like "Bash" to email yourself every time Claude runs a shell command
- **Notification hooks**: use the `Notification` event to get emailed when Claude Code surfaces a warning or requires your attention

For a full list of available hook events and matcher patterns, see the [Claude Code hooks tutorial](/content/blog/how-to-setup-claude-code-hooks-tutorial/index.html).

## Comparison: email delivery options for Claude Code hook scripts

| Tool | Setup effort | Best for | Cost |
| --- | --- | --- | --- |
| `msmtp` \\+ Gmail | Low | Solo developers, personal use | Free |
| SendGrid CLI | Medium | Teams, deliverability tracking | Free tier available |
| AWS SES CLI | Medium | AWS-native stacks | ~$0.10 per 1,000 emails |
| Mailgun CLI | Medium | API-first workflows | Free tier available |
| macOS `mail` \\+ local SMTP | Very low | Quick tests, internal relay | Free |

## Keep an eye on usage while automating

Automated hooks run in the background, but your Claude Code usage limits still apply. Long automation sessions consume tokens fast. To avoid hitting a hard cap mid-task, pair your hook setup with [Usagebar](/content/site-root.html), a macOS menu bar app that shows your live Claude Code usage and fires alerts at 50%, 75%, and 90% thresholds. It stores your credentials securely in the macOS Keychain and shows exactly when your usage window resets so you can schedule longer automation runs at the right time.

Usagebar is free for students and uses a pay-what-you-want model for everyone else. [Get Usagebar](/content/site-root.html) for instant download.

## Key takeaways

1. Use the `Stop` hook event in `settings.json` to trigger scripts at the end of every Claude Code session
2. Write a bash script that formats session context and pipes it to your SMTP tool of choice
3. Use `msmtp` for quick solo setups; use SendGrid or SES for team or production-grade delivery
4. Scope hooks to specific projects with project-level `.claude/settings.json` to avoid email noise
5. Monitor your usage limits with `/usage` in Claude Code or with [Usagebar](/content/site-root.html) to avoid mid-automation lockouts

## Sources

- [support.claude.com: Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [Usagebar: How to set up Claude Code hooks](/content/blog/how-to-setup-claude-code-hooks-tutorial/index.html)
- [Usagebar: How to use Claude Code slash commands](/content/blog/how-to-use-claude-code-slash-commands/index.html)
- [Usagebar: Claude Code slash commands list](/content/blog/claude-code-slash-commands-list/index.html)

### Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.