How to Build a Lead Nurture Agent with Claude Code

A lead nurture agent built with Claude Code is a scheduled task that reads a list of new leads, decides which follow-up email each one needs, sends it through a transactional email API, and logs every decision to a state file in your git repository. Armada Works runs this exact pattern against its own lead pipeline: a single agent handles the full Day 2 through Day 10 follow-up window without human involvement, and every send is a committed file you can review in a diff.

This tutorial walks through building one from scratch. You will design the state file, write the prompt that drives the agent's decisions, wire up the email integration, and iterate through the first week of runs. If you have not set up a Claude Code scheduled task before, start with Claude Code Scheduled Tasks for Marketing Teams for the foundational concepts, then come back here for the specific build.

The Problem: Manual Follow-Up Does Not Scale

Every founder knows the pattern. A lead downloads your guide, fills out a contact form, or books a call. You send a thank-you email manually. Then a production issue hits, a board deck needs finishing, or a customer escalation takes priority. The follow-up email you meant to send on Day 3 goes out on Day 9. Or never.

The usual fixes (marketing automation platforms, drip campaign tools) solve the timing problem but create a new one. They run on their own infrastructure, with their own data model, outside your codebase. You cannot see the decision logic in a git diff. You cannot revert a bad campaign with git revert. You cannot tune the copy by editing a markdown file and pushing the change.

A Claude Code nurture agent solves both problems. It runs on a schedule, so timing is automatic. It lives in your repo, so every decision (who received which email, when, and why) is a committed file you can read, search, and roll back.

Architecture: Three Files and an Email API

The system has four components:

• A prompt file (docs/agents/nurture-agent-prompt.md): the agent's instructions, constraints, and decision rules.
• A state file (docs/agents/state/nurture-agent-state.md): tracks which leads exist, what stage each is in, and what has been sent.
• A send log (docs/agents/state/nurture-send-log.md): an append-only record of every email dispatched, used for audit and debugging.
• An email API: any transactional email service with a scriptable API (Resend, Postmark, SendGrid, Amazon SES).

The agent's workflow on each run:

1. Read the state file.
2. Check for new leads (from a CSV export, a webhook payload, or a database query).
3. For each lead, determine the next email based on their stage and the number of days since entry.
4. Send the email via the API.
5. Update the state file and append to the send log.
6. Commit everything to git.

Here is the data flow in table form:

Step	Input	Output
Read state	nurture-agent-state.md	In-memory lead list
Check new leads	Lead source (CSV, DB query, webhook file)	Updated lead list with new entries
Determine next email	Lead stage + timing rules	Send decisions per lead
Send	Email API via shell script	Delivery confirmation or error
Update state	Send results	Updated nurture-agent-state.md
Log	Send results	Appended nurture-send-log.md
Commit	All changed files	Git commit with byline

Step 1: Design the State File

The state file is how the agent maintains memory between sessions. Every run starts by reading it; every run ends by updating it. Start with something minimal:

# Nurture Agent State

Last updated: 2026-06-07 09:00 PT

## Active Leads

| Lead | Email | Entered | Stage | Last Send | Next Send Due |
|------|-------|---------|-------|-----------|---------------|
| Jane Doe | jane@example.com | 2026-06-05 | welcome_sent | 2026-06-05 | 2026-06-07 |
| Alex Park | alex@example.com | 2026-06-06 | new | - | 2026-06-06 |

## Completed
(leads who received all sequence emails)

## Unsubscribed
(leads who opted out; agent must never send to these)

Each lead has a stage (new, welcome_sent, day3_sent, day7_sent, completed) and timestamps that tell the agent what to do next. The stage progression is the entire decision model. If you can describe it in a table, the agent can execute it.

Step 2: Write the Email Templates

Create a directory for your sequence emails:

docs/content/emails/nurture/
  email-1-welcome.md
  email-2-day3.md
  email-3-day7.md

Each file contains the subject, preview text, and body. Here is a minimal example for the Day 3 email:

---
subject: "The guide you downloaded (and what to check first)"
preview: "Three things worth looking at in the first 48 hours."
delay_days: 3
stage_trigger: welcome_sent
next_stage: day3_sent
---

Hi {{first_name}},

You downloaded the guide a few days ago.
Here are three things worth checking first...

The delay_days field tells the agent how many days after entry to send this email. The stage_trigger field tells it which leads are eligible. The agent reads the lead's Entered date, adds delay_days, compares to today, and checks that the lead's current stage matches stage_trigger. If both conditions pass, the email sends.

Step 3: Write the Prompt File

The prompt file is the agent's source code. It defines what the agent does on every run. Here is a practical starting version:

## Role
You are a lead nurture agent. You run daily at 9 AM.
Your job: send the right follow-up email to each active lead
at the right time, and log what you sent.

## Workflow
1. Read docs/agents/state/nurture-agent-state.md.
2. For each lead in Active Leads:
   - If stage is "new" and today >= Entered, send email-1-welcome.md.
     Update stage to "welcome_sent".
   - If stage is "welcome_sent" and today >= Entered + 3 days,
     send email-2-day3.md. Update stage to "day3_sent".
   - If stage is "day3_sent" and today >= Entered + 7 days,
     send email-3-day7.md. Update stage to "day7_sent".
   - If stage is "day7_sent", move to Completed.
3. Check /tmp/new-leads.csv for new leads. Add to Active Leads
   with stage "new".
4. Update the state file with all changes.
5. Append each send to docs/agents/state/nurture-send-log.md.
6. Commit all changed files.

## Constraints
- Never send more than one email to the same lead per day.
- Never send to a lead in the Unsubscribed list.
- Never modify the email templates. Read only.
- If the email API returns an error, log the error and skip
  that lead. Do not retry in the same run.
- Never print, log, or commit API keys or credentials.

A production prompt runs 200 to 400 lines. It includes rate limiting, bounce handling, timezone-aware send windows, CAN-SPAM compliance rules, and escalation paths. The version above is enough to get your first run working. You will iterate.

Robert Cowherd, founder of Armada Works, emphasizes the separation that makes the system safe: "The agent decides who gets which email and when. A separate script handles the actual send. The agent never sees the API key, and the script never makes decisions. That boundary is the entire security model."

Step 4: Wire the Email Send Script

The agent needs a way to dispatch emails without touching credentials directly. Write a small shell script that the agent calls:

#!/usr/bin/env bash
# scripts/send-nurture-email.sh
# Usage: bash scripts/send-nurture-email.sh to@email.com "Subject" body.txt

TO="$1"
SUBJECT="$2"
BODY_FILE="$3"

# Script reads API key from .env.local (never committed)
# and calls your email provider's API.
# The agent invokes this script; it never touches the key directly.

This script is the only component that interacts with your email provider. The agent calls it with three arguments (recipient, subject, path to the rendered body) and reads the exit code to determine success or failure. Every other component is pure markdown and git.

Your email provider choice does not matter much here. Resend is popular for new projects because of its developer-focused API. Postmark is reliable for transactional email. SendGrid and Amazon SES work at higher volumes. Pick whichever your team already uses.

Step 5: Run, Review, Iterate

Configure the Claude Code scheduled task to run daily at 9 AM, pointing at your prompt file and working directory. Then watch the output over the first week:

• Run 1: The agent reads an empty state file, picks up leads from your source, sends welcome emails. Check the commit: did it update the state file correctly? Did it log the send?
• Run 2: Leads who received the welcome email yesterday are now at stage welcome_sent. If any entered three or more days ago, they get email 2. Check the timing logic.
• Run 3: You notice the agent is logging too much detail, or not enough. Edit the prompt. Commit. The next run uses the updated prompt automatically.

This iteration loop is the core workflow: run, review the diff, tune the prompt, repeat. Robert Cowherd describes the experience of building it: "The first prompt was 40 lines. By the end of the first week it was 180. Every line came from a real mistake the agent made in a real run. That is the calibration process, and it is the same whether you are building a nurture agent or an SEO agent."

Within a week, the system handles your entire follow-up sequence without supervision. Within two weeks, you stop checking every diff and start trusting the git log.

What You Learn by Building It

Building a nurture agent teaches you patterns that apply to every agent in a fleet:

• State file design. Every agent needs persistent memory across sessions. The table format (lead, stage, timestamps) is the simplest version of a pattern that scales to content queues, SEO audit logs, and sales pipelines.

• Prompt-as-code. The prompt file is the agent's source code. You iterate on it the same way you iterate on application code: change, commit, observe, change again.

• Separation of concerns. The agent makes decisions. Scripts handle side effects (sending email, calling APIs). State files handle memory. Git handles auditability. Each component does one thing.

• Failure costs nothing. A bad send gets logged and committed. You revert the commit, fix the prompt, and re-run. Nothing breaks permanently because everything is in version control.

These four patterns are the same ones that underpin a multi-agent fleet running content, SEO, outbound, and lead triage. The nurture agent is the simplest complete example of all four.

When to Build It Yourself vs. Hire a Consultancy

A single nurture agent is buildable in an afternoon. If your sequence is three emails over ten days, your lead volume is low (under 50 leads per week), and you are comfortable iterating on prompts, building it yourself is the right call.

The calculus changes when:

• You need multiple agents sharing state. The content agent reads the nurture agent's send log to avoid emailing a lead who just received a blog link. That coordination requires shared state file conventions and a synthesizer agent reading both outputs.
• You need production-grade constraints: rate limiting, bounce handling, unsubscribe compliance, timezone-aware send windows.
• You need the nurture agent to coordinate with a CMO synthesizer that reads all agent briefs each morning and writes a single summary for the founder.
• Your lead volume means a missed send or double-send has real revenue impact.

Armada Works offers a Pilot engagement ($2,500 to $4,000, one week) that ships a production-grade nurture agent (or any single agent you need most) into your repo. The Pilot fee credits 100% toward a longer engagement if you continue within 30 days. You keep the prompt, the state files, and the full commit history regardless of what you decide.

Frequently Asked Questions

How long does it take to build a lead nurture agent with Claude Code?

A basic three-email nurture agent takes two to four hours to set up from scratch: one hour for the state file and email templates, one to two hours for the prompt file, and thirty minutes for the email send script. Expect another three to five hours over the first week iterating on the prompt based on actual run output. The prompt is where the real calibration happens.

What email provider works best with a Claude Code nurture agent?

Any transactional email API works. The agent does not interact with the API directly; it calls a shell script that handles the send. Resend is popular for new projects because of its clean developer API. Postmark is solid for transactional reliability. SendGrid and Amazon SES handle higher volumes. Pick whichever your team already uses.

Can the nurture agent handle unsubscribes?

Yes. Maintain an Unsubscribed section in the state file. When your email provider reports an unsubscribe (via webhook or status check), add the lead to that list. The agent's prompt includes a hard constraint to never send to anyone in the Unsubscribed section. For production use, also include an unsubscribe link in each email template that routes to your application's unsubscribe endpoint.

How is this different from Mailchimp or HubSpot drip campaigns?

Traditional drip campaigns run on the vendor's infrastructure with a visual workflow builder. A Claude Code nurture agent runs in your git repo. You see every decision in a git diff, you control the logic by editing a markdown prompt file, and you own the system outright when you stop paying for the agent's runtime. The agent can also make judgment calls that rule-based tools cannot: skip a send if a lead just booked a discovery call, or escalate if a lead has not opened any emails. For a deeper comparison, see Marketing Agents vs. Marketing Automation.

Does the agent need direct access to my CRM?

Not necessarily. The simplest setup reads new leads from a CSV export or a JSON payload dumped by a webhook. If your leads live in a CRM, write a small script that exports new entries to a file the agent reads at the start of each run. The agent never needs direct CRM access, which keeps the security surface small.

What does a production nurture agent prompt look like compared to this tutorial?

A production prompt runs 200 to 400 lines. It adds rate limiting, bounce handling, timezone-aware send windows, compliance constraints (CAN-SPAM, GDPR opt-in verification), escalation paths for repeated failures, and coordination rules for reading other agents' state files. The architecture (state file, prompt file, send script, git commit log) stays identical. The prompt just gets more specific about edge cases.

---

If you want to see how a production nurture agent works inside a coordinated fleet, or you want one shipped into your repo in a week, book a free 30-minute discovery call. We will walk through your current follow-up process and tell you whether an agent is the right fit for your pipeline.