Most small teams waste time opening the same kinds of emails over and over again: billing requests, bug reports, partnership outreach, and vague messages that still need a human reply. A lightweight AI triage agent can reduce that first-pass workload by reading incoming text, assigning a category, estimating urgency, and producing a short reason that a human can review before taking action.
This guide shows a practical starter pattern for building that workflow in Python with the OpenAI Responses API. The goal is not to create a fully autonomous help desk. The goal is to build a reliable classification layer that turns raw email text into structured data your app can route, log, or review. If you later want to expand the project, you can connect the same output to your own database, CRM, or a simple internal dashboard.
Why this AI agent pattern works
Email triage is a good first agent project because the task is narrow and the output is easy to validate. Instead of asking the model to reply directly to the user, you ask it to return a small structured object such as category, urgency, escalation flag, and summary. That makes the workflow easier to review and safer to automate.
OpenAI's current documentation recommends the Responses API for new projects and recommends Structured Outputs when you need the model to return predictable JSON that matches a schema. That is exactly what a triage layer needs. You do not want free-form paragraphs when your downstream code expects fields like label, priority, and needs_human.
This pattern also fits how Snapdo articles should work: clear scope, practical result, and honest limits. We are building a routing helper, not a magic inbox manager. A human can still make the final decision, but the repetitive reading and sorting step becomes much faster.
What you need before you start
You need Python 3.10 or newer, an OpenAI API key, and the official Python SDK. Create a new virtual environment if you want to keep the project clean. Install the SDK with pip:
python -m venv .venv
.venv\Scripts\activate
pip install openai
Set your API key as an environment variable before running the script:
setx OPENAI_API_KEY "your_api_key_here"
If you are new to utility scripts, articles in the Tools section and simple automation walkthroughs in Coding are good companion reads because they follow the same small-script mindset.
Design the output schema first
Before writing code, decide what your application actually needs from each email. A common mistake is to start prompting without defining the final shape. In practice, a good starter schema for triage looks like this:
- label: one of
billing,support,sales,security, orother - priority:
low,medium, orhigh - needs_human:
trueorfalse - summary: one short sentence explaining the email
- reason: a short explanation for why the label was chosen
Keeping the schema small improves consistency. It also makes debugging easier because you can compare raw email content against the exact fields your code receives. If a label looks wrong, you can inspect the reason field and refine the prompt instead of guessing.
OpenAI's Structured Outputs guidance is useful here because it focuses on returning data that matches a schema rather than hoping free-form JSON will always be valid. For an agent that feeds other systems, predictable structure matters more than eloquent wording.
Build the Python triage script
The script below sends email text to the model, asks for a strict JSON structure, and prints the parsed result. This is enough for a first internal tool, and you can later plug the returned object into routing rules or a review queue.
from openai import OpenAI
from pydantic import BaseModel
class EmailTriage(BaseModel):
label: str
priority: str
needs_human: bool
summary: str
reason: str
client = OpenAI()
email_text = """
Subject: Invoice mismatch for March
Hi team,
We were charged twice for the March plan after upgrading seats.
Can someone review the invoice and confirm whether we should expect a refund?
"""
response = client.responses.parse(
model="gpt-5.2",
input=[
{
"role": "system",
"content": (
"You are an email triage agent. "
"Classify the message, estimate priority, and be conservative. "
"If the message is ambiguous, set needs_human to true."
),
},
{
"role": "user",
"content": email_text,
},
],
text_format=EmailTriage,
)
triage = response.output_parsed
print(triage.model_dump())There are three important details in that example. First, the system instruction is narrow and operational. Second, the schema is small enough that the model is not juggling unnecessary fields. Third, the agent is told to be conservative when the message is ambiguous. That last instruction matters because the safest triage agent is one that escalates uncertainty instead of pretending to know everything.
If you do not want to use responses.parse, you can also define a JSON schema manually. The principle stays the same: keep the output fixed, machine-readable, and easy to validate.
Add practical guardrails before automation
Do not send live production emails directly into an auto-reply workflow on day one. Start with a review step. Store the returned object, inspect the labels, and only then decide whether your app should route messages automatically. A conservative rollout avoids the classic mistake of trusting a neat demo too early.
Useful guardrails include:
- force
needs_human = truefor security, legal, or payment disputes - reject empty or extremely short emails before sending them to the model
- log the original email text and the model result together for auditability
- limit labels to categories your team genuinely uses
- review ambiguous cases weekly and tighten the prompt or schema when patterns appear
If you later decide to connect this project to a broader automation stack, keep the same philosophy used in small internal tools such as local summarizers: start with a narrow job, inspect the output, then scale only after the structure is stable.
What to improve next
Once the basic classifier works, the next upgrade is usually routing logic. For example, billing emails can go to finance, bug reports can be pushed into a queue, and high-priority support tickets can trigger a notification. Another good improvement is adding confidence handling. If your prompt or schema does not support confidence directly, use needs_human as the operational safety valve and keep it biased toward review.
You can also expand the same pattern into a multi-step workflow: classify the email, summarize it for the operator, and suggest the next action. Keep those steps separate. A clear pipeline is easier to audit than one giant prompt that tries to do classification, escalation, routing, and reply generation all at once.
For a serious production version, treat this article as the practical starting point and keep the official docs close. The OpenAI docs are the source of truth for the Responses API, Structured Outputs, and the broader Agents SDK ecosystem. This article focuses on the stable starter pattern: strict structure, narrow scope, and a human review path.
Sources
OpenAI Structured Outputs Guide
Disclaimer: "All content is for educational use only. Snapdo and its authors are not liable for any financial losses, data loss, or hardware damage."