Agent Patterns

How do I use labels to track email state?

Use labels to manage agent workflow state on emails and threads.

Labels are string-based tags you attach to messages and threads. They are the primary way agents track state, classify emails, and filter conversations in AgentMail.

Adding labels when sending

You can attach labels directly when sending a message:

Python
1client.inboxes.messages.send(
2    inbox_id="agent@yourdomain.com",
3    to=["prospect@example.com"],
4    subject="Quick question",
5    text="Hi, I wanted to ask about...",
6    html="<p>Hi, I wanted to ask about...</p>",
7    labels=["outreach", "first-touch", "tech-vertical"]
8)

Updating labels on existing messages

Add or remove labels on messages that have already been sent or received. This is how agents change the state of a conversation as they process it:

Python
1# Mark a message as processed
2client.inboxes.messages.update(
3    inbox_id="agent@yourdomain.com",
4    message_id=msg.message_id,
5    add_labels=["processed", "positive-sentiment"],
6    remove_labels=["unread"]
7)

Filtering by label

List messages or threads that match specific labels. This is where labels become powerful for building agent workflows:

Python
1# Get all unread messages in an inbox
2unread = client.inboxes.messages.list(
3    inbox_id="agent@yourdomain.com",
4    labels=["unread"]
5)
6
7# Get threads that need a follow-up from a specific campaign
8follow_ups = client.inboxes.threads.list(
9    inbox_id="agent@yourdomain.com",
10    labels=["q4-campaign", "needs-response"]
11)
12
13# Get escalations that need human review
14escalations = client.inboxes.messages.list(
15    inbox_id="agent@yourdomain.com",
16    labels=["escalation", "needs-human-review"]
17)

Common label patterns for agents

LabelPurpose
unread / readTrack which messages the agent has seen
unreplied / repliedTrack which threads need a response
outreach / inboundClassify message direction
needs-human-reviewRoute to a human for oversight
escalationFlag high-priority issues
processedAgent has finished handling this message
positive / negativeSentiment classification
campaign-{name}Track which campaign generated the email

Labels are free-form strings. Use whatever naming convention makes sense for your agent’s workflow.

Example: agent workflow with labels

Here is a complete pattern for an agent that processes inbound emails, classifies them, and tracks state:

Python
1from agentmail import AgentMail
2
3client = AgentMail()
4
5# Find threads that need a reply
6unreplied = client.inboxes.threads.list(
7    inbox_id="support@yourdomain.com",
8    labels=["unreplied"]
9)
10
11for thread_item in unreplied.threads:
12    # Get the full thread
13    thread = client.threads.get(thread_id=thread_item.thread_id)
14    last_message = thread.messages[-1]
15    
16    # Classify the message (your agent logic here)
17    category = classify(last_message.extracted_text or last_message.text)
18    
19    if category == "needs-human":
20        # Escalate: add label, skip auto-reply
21        client.inboxes.messages.update(
22            inbox_id="support@yourdomain.com",
23            message_id=last_message.message_id,
24            add_labels=["needs-human-review", "escalation"],
25            remove_labels=["unreplied"]
26        )
27    else:
28        # Auto-reply and mark as handled
29        reply_text = generate_reply(last_message, category)
30        client.inboxes.messages.reply(
31            inbox_id="support@yourdomain.com",
32            message_id=last_message.message_id,
33            text=reply_text
34        )
35        client.inboxes.messages.update(
36            inbox_id="support@yourdomain.com",
37            message_id=last_message.message_id,
38            add_labels=["replied", "processed", category],
39            remove_labels=["unreplied"]
40        )

Best practices

  • Be consistent: Pick a naming convention (e.g., kebab-case) and stick with it across all your agents
  • Use prefixes for grouping: Labels like status-pending, priority-high, campaign-q4 are easier to manage at scale
  • Keep it concise: A message with too many labels becomes hard to query. Aim for a meaningful, focused set
  • Combine with threads: Filter threads by label to find conversations in a specific state, then get the thread details to process them

For more details, see the Labels core concept documentation.