Labels

What are Labels?

Labels are simple, string-based tags that you can attach to your Messages and Threads. They are the primary mechanism for organizing, categorizing, and managing the state of your conversations, whether its automatically bucketing threads into specific categories for your outbound campaign, to segmenting warm leads for your outreach, to categorizing inbound into low-ticket, medium-ticket, high-ticket customers.

A Message can have multiple Labels, allowing you to create a flexible and powerful system for managing complex workflows.

Use Cases for Labels

By strategically applying Labels, you can build sophisticated agent systems. Here are a few common use cases:

Core Capabilities

Here’s how you can programmatically work with Labels.

1. Adding Labels When Sending a Message

You can attach an array of Labels directly when you send a Message.

1
sent_message = client.inboxes.messages.send(
2
    inbox_id="outbound@agentmail.to",
3
    to=["test@example.com"],
4
    subject="Following up on our conversation",
5
    text="Here is the information you requested.",
6
    labels=["follow-up", "q4-campaign"]
7
)

2. Adding or Removing Labels on an Existing Message

You can modify the Labels on a Message that has already been sent using the update (PATCH) method. This is perfect for changing the state of a conversation as your agent works on it.

1
# Let's add a 'resolved' label to a message
2
3
client.messages.update(
4
inbox_id='outbound@domain.com',
5
message_id='<abc123@agentmail.to>',
6
add_labels=["resolved"],
7
remove_labels=['unresolved']
8
)

3. Filtering by Labels

This is where Labels become truly powerful. You can list Threads, Messages, and Drafts by filtering for one or more Labels, allowing you to create highly targeted queries.

1
# Find all threads from a specific campaign that need a follow-up
2
filtered_threads = client.inboxes.threads.list(
3
    inbox_id = 'outbound-agent@domain.com',
4
    labels=[
5
        "q4-campaign",
6
        "follow_up"
7
    ]
8
)
9
10
print(f"Found {filtered_threads.count} threads that need a follow-up.")

Copy for Cursor / Claude

Copy one of the blocks below into Cursor or Claude for complete Labels usage in one shot.

1
"""
2
AgentMail Labels — copy into Cursor/Claude.
3
4
Labels are string tags on Messages and Threads for state, campaigns, triage.
5
6
- Send: messages.send(..., labels=["campaign", "follow-up"])
7
- Update: inboxes.messages.update(inbox_id, message_id, add_labels=[...], remove_labels=[...])
8
- Filter: messages.list(inbox_id, labels=[...]), threads.list(inbox_id, labels=[...]), drafts.list(inbox_id, labels=[...])
9
10
Use kebab-case or snake_case consistently.
11
"""
12
from agentmail import AgentMail
13
14
client = AgentMail(api_key="YOUR_API_KEY")
15
16
# Send with labels
17
client.inboxes.messages.send("out@agentmail.to", to="user@example.com", subject="Hi", text="Body", labels=["q4-campaign"])
18
19
# Update labels
20
client.inboxes.messages.update("out@agentmail.to", "<abc123@agentmail.to>", add_labels=["resolved"], remove_labels=["pending"])
21
22
# Filter by labels
23
threads = client.inboxes.threads.list("out@agentmail.to", labels=["q4-campaign", "follow-up"])

Best Practices

• Be Consistent: Establish a clear and consistent naming convention for your labels (e.g., kebab-case, snake_case).
• Use Prefixes: For state management, consider using prefixes like status-pending or priority-high to create an organized system.
• Don’t Over-Label: While you can add many Labels, aim for a concise and meaningful set to keep your system manageable.