Guide: Sending & Receiving Email

This guide walks you through the complete, practical workflow of an agent having a conversation. While the Core Concepts pages detail the individual API calls, this guide shows you how to stitch them together to create a functional conversational loop.

The Foundation: Sending HTML & Text

As a quick reminder from our Messages documentation, it’s a critical best practice to always provide both an html and a text version of your email. This ensures readability on all email clients and significantly improves deliverability.

1
# Always provide both html and text when possible
2
client.inboxes.messages.send(
3
    inbox_id="outreach@agentmail.to",
4
    to=["potential-customer@example.com"],
5
    subject="Following up",
6
    text="Hi Jane,\n\nThis is a plain-text version of our email.",
7
    html="<p>Hi Jane,</p><p>This is a <strong>rich HTML</strong> version of our email.</p>",
8
    labels=["outreach-campaign"]
9
)

The Conversational Loop

A common task for an agent is to check for replies in an Inbox and then respond to them. While using Webhooks is the most efficient method for this, you can also build a simple polling mechanism.

Here’s the step-by-step logic for a polling-based conversational agent.

1
# Find all threads in this inbox that are marked as unreplied
2
threadsRes = client.threads.list(
3
    labels = ["unreplied"]
4
)
5
if threadsRes.count == 0:
6
    print("No threads need a reply.")
7
else:
8
    # Let's work on the first unreplied thread
9
    thread_to_reply_to = threadsRes.thread[0]

1
# Get the full thread object to access its messages
2
thread_details = client.threads.get(thread_to_reply_to.thread_id)
3
4
# The last message in the list is the one we want to reply to
5
last_message = thread_details.messages[-1]
6
message_id_to_reply_to = last_message.message_id

1
# Send the reply
2
client.inboxes.messages.reply(
3
    inbox_id="support@agentmail.to",
4
    message_id=message_id_to_reply_to,
5
    text="This is our agent's helpful reply!"
6
)
7
8
# Update the labels on the original message
9
client.inboxes.messages.update(
10
    inbox_id="support@agentmail.to",
11
    message_id=message_id_to_reply_to,
12
    add_labels=["replied"],
13
    remove_labels=["unreplied"]
14
)

Scheduling Emails

Instead of sending immediately, you can schedule emails for a future time—perfect for delivering messages during business hours or spacing out outreach.

Create a Draft with the send_at field and AgentMail handles the rest. The email is automatically sent at the specified time.

1
from datetime import datetime, timedelta
2
3
# Schedule for tomorrow at 9 AM UTC
4
send_time = (datetime.utcnow() + timedelta(days=1)).replace(hour=9, minute=0, second=0)
5
6
client.inboxes.drafts.create(
7
    inbox_id="outreach@agentmail.to",
8
    to=["prospect@example.com"],
9
    subject="Quick question about your workflow",
10
    text="Hi, I noticed you're using...",
11
    html="<p>Hi, I noticed you're using...</p>",
12
    send_at=send_time.isoformat() + "Z"
13
)