← All Posts

How to Do Automated Email Reports on Claude Code

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

What are Claude Code hooks and why they matter for automation

Claude Code hooks 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)
  • 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 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.

#!/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:

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, 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:

{
  "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:

# 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 ~/.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 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 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.

Comparison: email delivery options for Claude Code hook scripts

ToolSetup effortBest forCost
msmtp + GmailLowSolo developers, personal useFree
SendGrid CLIMediumTeams, deliverability trackingFree tier available
AWS SES CLIMediumAWS-native stacks~$0.10 per 1,000 emails
Mailgun CLIMediumAPI-first workflowsFree tier available
macOS mail + local SMTPVery lowQuick tests, internal relayFree

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, 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 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 to avoid mid-automation lockouts

Sources

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.

Get Usagebar