How to Build an AI Email Agent
That Replies Like a Human

Contents

Preface: what this is, and where it is used

Before the how, the why. The thing you are about to build, a loop that takes in a message, understands it, and answers in natural language, is not a novelty email bot. It is the reusable core of an entire category of production AI.

At Loandock I use this exact loop as a borrower communications agent: it emails and texts borrowers, asks for the documents a loan file is still missing, and reads what comes back. Learn the pattern once here on email, and you can point it at almost any repetitive, language heavy task a person is doing by hand today.

1. Introduction: the brain and the pen

An AI email agent is a program that receives an email, figures out what it means, and writes and sends a reply on its own, with no human drafting each message.

Here is the mental model that keeps these systems reliable: separate the brain from the pen. A deterministic "brain" owns the overarching agenda, the actual job to be done, such as verify this person's income, send this month's payment reminders, or run a support conversation to resolution. It decides what should happen and when, in plain code you can trust. The "pen" is the language layer, a large language model (LLM) whose only job is to turn the brain's intent into words a human is happy to read. The brain decides; the pen writes.

1.1 One master agent, many hands

In a full system, the email agent is just one "hand" of a larger master agent. Other hands parse documents, verify them, and file them. This guide builds one hand: the email pen.

1.2 Who does the work

A well built agent leans on plain code for almost everything and calls the model only for the narrow part it is genuinely best at: language and judgment. In my production system, the deterministic brain does the large majority of the work, and the LLM pen a small, carefully scoped slice.

1.3 Why not one big autonomous agent

2. How it sounds human

Sounding human is not one trick. It is a clear voice specification given to the model as a system prompt, plus a rule that it never invents facts. The lines below are the most important sections and hacks from my own proven production prompt, adapted for this guide (company name removed, em dashes stripped to match its own rule). The single most important step in this whole guide is writing something like it. The full, unabridged version is listed in Appendix A.

2.1 The system prompt (real, adapted)

You are the communications agent for one customer.
You own every message they get, across SMS and email (your two hands).
You are warm, clerical staff. You are NOT the decision maker.

# Voice and tone
You sound like a real, sharp, caring human assistant texting
someone you actually want to help. Concise, plainspoken, never corporate.

- You are on their side. Frame every ask warm and forward looking.
- Plain everyday words. No jargon, no acronyms, no internal codes.
  Translate every industry term into the plain idea behind it.
- No em dashes, no en dashes, no emojis. Commas, colons, periods only.
- Mirror the customer. A short reply gets a short reply.
- Text like a real person. One or two sentences. Greet once.
- No padding. Skip filler greetings, sign offs, and tacked on thanks.
- Only reference what actually happened. A fresh ask is asked plainly.

# Your lane
Never discuss rates, fees, payments, approval odds, or terms.
Those go to a licensed human. When unsure, hand off, do not guess.

# Context (handed in every turn)
{{directive}}  {{customer}}  {{your_notes}}  {{recent_thread}}
{{parsed_attachments_json}}

2.2 Robotic reply vs human reply

Same request for the same missing document. The difference is entirely in the prompt.

3. Requirements

To follow along, you will need:

• A Claude API key from the Anthropic Console, the LLM that reads and writes.
• An AgentMail account and API key, plus a domain you own for sending.
• ngrok (free) to expose your local server to the internet during development.
• A Railway account for deployment.
• Node.js 18 or newer installed locally.

Those rules are not left to the model's goodwill. In the real system they live in one gate that every outbound message passes through, in plain code, before it can leave. Two of them, adapted from that gate:

// Fail closed. While live, a real message only reaches an allowlisted address.
// An EMPTY allowlist sends to NOBODY (dry run), never to everyone. You must
// set "*" on purpose to go fully live.
function allowed(addr) {
  if (ALLOWLIST === "*")  return true
  if (!ALLOWLIST.length)  return false          // empty means nobody
  return ALLOWLIST.includes(addr.toLowerCase())
}

// Rates, fees, APR, approval odds: ALWAYS hold for a human, even on auto approve.
const PROHIBITED = /\b(apr|interest rate|rate lock|fees?|closing costs?|approval odds)\b/i

async function sendGated(msg) {                 // returns a GateStatus
  const body = lint(msg.body)                   // strip em dashes and emojis first
  if (customer.opted_out)               return "blocked_opt_out"
  if (PROHIBITED.test(body) || !AUTO_APPROVE)
                                        return hold(body)     // "held_for_approval"
  if (!LIVE || !allowed(msg.to))        return "dry_run"     // record it, send nothing
  await record(body, "sending")               // record FIRST, never send unlogged
  const { id } = await mail.send(msg.to, body)
  await finalize(id, "sent")
  return "sent"
}

[orchestrator] one process up: webhook + advance / scheduler ticks
[gate] draft ready for sarah@example.com
[gate] dry_run: COMMS_LIVE is off, nothing sent (saved as draft)

$ export COMMS_LIVE=true COMMS_ALLOWLIST=sarah@example.com

[gate] held_for_approval: body mentions "rate", waiting on a human
[gate] sent (msg_01H9x2...) cc 2

5. Step by step instructions

Note. These steps lay out the overarching flow, not every click. The exact setup details for AgentMail, Railway, Vercel, and the other tools live in their own official documentation (see References), which is thorough and kept current. The concrete, real world version of the deploy commands is in Appendix C.

Documentation: Claude / Anthropic ↗ opens in a new tab

Documentation: ngrok ↗ opens in a new tab

// AgentMail calls this URL every time an email arrives.
app.post("/api/webhooks/agentmail", express.json(), async (req, res) => {
  const msg = req.body.message

  // 1. draft a human reply using the system prompt from Figure 2
  const draft = await claude.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 400,
    system: SYSTEM_PROMPT,
    messages: [{ role: "user", content: msg.text }],
  })

  // 2. hand the reply back to AgentMail to send, in the same thread
  await mail.inboxes.messages.reply(inboxId, msg.id, { text: draft.text })

  res.sendStatus(200)
})

Reading an attachment is really two problems. Ingestion pulls the file off the email and turns it into text and structured fields (above). Understanding is the harder half: is this the right document, is it current, and is it complete? One model call is not enough to trust, so the file runs through a short pipeline where a second, different model has to agree before anything is filed. Anything uncertain is handed to a person, never pushed through on a guess.

Here is the first half of that pipeline, adapted from the production system: pull the file, skip the junk, and let Claude read it into structured JSON.

// 1. Pull the file off the email. AgentMail returns a short lived URL.
const { downloadUrl } = await mail.inboxes.messages.getAttachment(inboxId, msg.id, att.id)
const bytes = Buffer.from(await (await fetch(downloadUrl)).arrayBuffer())

// 2. Skip inline images (signature logos, tracking pixels). Keep real files.
if (att.inline) continue

// 3. Let Claude read it. A PDF becomes a "document" block, an image an "image"
//    block, and output_config forces a structured JSON answer.
const res = await claude.messages.create({
  model: "claude-opus-4-8",
  system: CLASSIFY_PROMPT,
  messages: [{ role: "user", content: [
    { type: "document", source: { type: "base64",
        media_type: att.contentType, data: bytes.toString("base64") } },
    { type: "text", text: "What document is this, and what does it show?" },
  ]}],
  output_config: { format: { type: "json_schema", schema: DOC_SCHEMA } },
})
const doc = JSON.parse(res.content[0].text)

// 4. Invariants enforced in code, not trusted to the model:
if (doc.confidence === "low")          doc.needs_human = true  // unsure: a person looks
if (doc.doc_type && !doc.matched_item) doc.needs_human = true  // no match: a person looks

[agentmail] skipped 1 inline image (signature logo, not a document)
[intake] read attachment "statement.pdf" with Claude vision:
{
  "doc_type": "bank_statement",
  "matched_item": "two_recent_statements",
  "confidence": "high",
  "complete": true,
  "needs_human": false,
  "page_count": 3,
  "document_date": "2026-05-31",
  "account_holder_name": "Sarah Chen"
}
[intake] high confidence and matched: passed to the verify step

Documentation: Vercel ↗ opens in a new tab

Documentation: Supabase ↗ opens in a new tab

For the concrete, real world version of these three deploys (exact commands, variables, and the one replica rule), see Appendix C.

6. The full workflow, end to end

Putting every step together, here is what happens each time an email arrives. Notice that the brain (plain code) drives the sequence and the safety gate, and the pen (the model) is called only to write.

7. Conclusion, resources, accessibility

You now have the full loop: an agent that receives an email, understands it and its attachments, and replies in a human voice, deployed and running. From here, formalize the split between the brain and the pen, add memory with Supabase, and keep a human review step until you trust it at scale.

Further resources. The official docs for Claude, AgentMail, Railway, ngrok, and Supabase (see References) are the fastest way to go deeper on any one step.

Accessibility. This document uses semantic headings, a clickable contents index, alt text on every figure, high contrast text, and readable type sizes, so it works with screen readers and when printed in grayscale. An interactive web version of this guide, with live links and animated diagrams, is published at jhaarnav.github.io/AgentMail-Tutorial and targets WCAG 2.1 AA.

Modes used in this document: written (instructions), visual (mind map, charts, workflow and architecture diagrams, code), and electronic (clickable contents and live hyperlinks).

8. Where this goes next

This guide covers the core build: one hand of a larger agent. Natural next steps to take it further:

9. References

APA style. Links are to each tool's official documentation.

1. Anthropic. (2026). Claude (Opus 4.8) [Large language model]. Used only for the visual elements of this document (layout, headers and footers, tables, diagrams, and placeholder visuals). All written content and technical ideas are the author's own or paraphrased from the author's production work. https://claude.ai
2. Anthropic. (2026). Claude API documentation. https://docs.anthropic.com
3. AgentMail. (2026). AgentMail documentation. https://docs.agentmail.to
4. Railway. (2026). Railway documentation. https://docs.railway.com
5. Vercel. (2026). Vercel documentation. https://vercel.com/docs
6. ngrok. (2026). ngrok documentation. https://ngrok.com/docs
7. Supabase. (2026). Supabase documentation. https://supabase.com/docs

Appendix A: the full system prompt

Section 2.1 shows the most important lines. Here is the fuller, section by section version of the communications agent prompt from my production system, adapted for this guide: the company name is removed and em dashes are stripped to match the prompt's own rule.

Appendix B: glossary

Appendix C: final production grade deployment

Section 5 is the shape of the build. Here is the concrete version, distilled from the production deploy of the system this guide is based on. It rests on one split: the dashboard runs on Vercel (serverless), the always on agent worker runs on Railway (a single replica), and both share one Postgres database on Supabase.