Messages

A message represents a single email -- either sent by your agent (outbound) or received from an external sender (inbound). Messages are the fundamental unit of communication in AgentPost.

Key properties

Property	Description
`id`	Unique identifier (prefix `msg_`)
`inbox_id`	The inbox this message belongs to
`thread_id`	The conversation thread this message is part of
`direction`	`inbound` (received) or `outbound` (sent)
`subject`	Email subject line
`from_address`	Sender email and name
`to_addresses`	Array of recipient emails and names
`cc_addresses`	Carbon copy recipients
`bcc_addresses`	Blind carbon copy recipients
`text_body`	Plain text body
`html_body`	HTML body
`extracted_text`	Clean text extracted from HTML (no tags, no quoted replies)
`labels`	Array of string labels
`has_attachments`	Whether the message has file attachments

Sending messages

Create an outbound message by posting to the inbox's messages endpoint.

const message = await client.messages.send('inb_abc123', {
  to: [{ email: 'ops-team@acmeco.com', name: 'Ops Team' }],
  subject: 'Deploy completed: api-server v2.4.1',
  text_body: 'Deployment of api-server v2.4.1 to production completed successfully.\n\nChanges:\n- Fixed rate limiter race condition\n- Added health check retry logic\n\nAll integration tests passing.',
});

message = client.messages.send(
    inbox_id="inb_abc123",
    to=[{"email": "ops-team@acmeco.com", "name": "Ops Team"}],
    subject="Deploy completed: api-server v2.4.1",
    text_body="Deployment of api-server v2.4.1 to production completed successfully.\n\nChanges:\n- Fixed rate limiter race condition\n- Added health check retry logic\n\nAll integration tests passing.",
)

curl -X POST https://api.agent-post.dev/api/v1/inboxes/inb_abc123/messages \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "ops-team@acmeco.com", "name": "Ops Team"}],
    "subject": "Deploy completed: api-server v2.4.1",
    "text_body": "Deployment of api-server v2.4.1 to production completed successfully."
  }'

Receiving messages

Inbound messages arrive automatically when someone sends email to your inbox address. You can retrieve them by listing messages or by subscribing to webhooks for real-time notification.

// List inbound messages
const messages = await client.messages.list('inb_abc123', {
  direction: 'inbound',
  limit: 10,
});

// Get a specific message by ID
const message = await client.messages.get('msg_def456');

# List inbound messages
messages = client.messages.list(
    inbox_id="inb_abc123",
    direction="inbound",
    limit=10,
)

# Get a specific message by ID
message = client.messages.get("msg_def456")

# List inbound messages
curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123/messages?direction=inbound&limit=10" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

# Get a specific message
curl "https://api.agent-post.dev/api/v1/messages/msg_def456" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Reply and forward

Reply to a message to continue the conversation in the same thread. Forward a message to send it to a new recipient.

// Reply -- stays in the same thread, adds "Re:" prefix
const reply = await client.messages.reply('msg_def456', {
  text_body: 'Thanks for the report. I have escalated this to the engineering team.',
});

// Forward -- creates a new thread with "Fwd:" prefix
const forwarded = await client.messages.forward('msg_def456', {
  to: [{ email: 'eng-lead@acmeco.com', name: 'Engineering Lead' }],
  text_body: 'FYI -- see the original message below for context.',
});

# Reply
reply = client.messages.reply(
    message_id="msg_def456",
    text_body="Thanks for the report. I have escalated this to the engineering team.",
)

# Forward
forwarded = client.messages.forward(
    message_id="msg_def456",
    to=[{"email": "eng-lead@acmeco.com", "name": "Engineering Lead"}],
    text_body="FYI -- see the original message below for context.",
)

# Reply
curl -X POST https://api.agent-post.dev/api/v1/messages/msg_def456/reply \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text_body": "Thanks for the report. I have escalated this to the engineering team."}'

# Forward
curl -X POST https://api.agent-post.dev/api/v1/messages/msg_def456/forward \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "eng-lead@acmeco.com", "name": "Engineering Lead"}],
    "text_body": "FYI -- see the original message below for context."
  }'

extracted_text vs html_body

AgentPost provides both the raw HTML body and a cleaned plain-text extraction:

html_body -- The original HTML content of the email, including formatting, images, and quoted reply sections
text_body -- The plain text version (if provided by the sender)
extracted_text -- Clean text extracted from the HTML body with tags stripped and quoted reply sections removed. This is the most useful field for AI agents that need to understand the message content without parsing HTML.

Use extracted_text for AI processing

When passing message content to an LLM, use extracted_text rather than html_body. It removes HTML noise, email signatures, and quoted reply chains, giving the model clean content to work with.

Message metadata

Messages include several metadata fields:

Field	Description
`email_message_id`	The RFC 5322 Message-ID header value
`in_reply_to`	Message-ID of the email being replied to
`references`	Array of Message-IDs forming the reply chain
`headers`	Raw email headers (inbound messages only)

Relationships

Every message belongs to exactly one inbox (inbox_id)
Every message belongs to exactly one thread (thread_id), created automatically
Messages can have labels -- string tags for categorization
Messages can have attachments -- files uploaded or received with the email
Outbound messages are sent via the configured email provider (AWS SES)

Tips

Always provide both text_body and html_body when sending -- some recipients prefer or require plain text
Use extracted_text for AI processing of inbound messages
Reply preserves the thread; forward creates a new thread
Subject prefixes (Re: and Fwd:) are added automatically -- do not add them yourself
Messages are immutable after creation. You cannot edit a sent or received message.

Messages

On this page