AgentPost
Get Started

Quickstart

Create your first inbox and send an email in under 5 minutes

This guide walks you through the essential steps to get started with AgentPost: getting an API key, creating an inbox, sending an email, and checking for received messages.

Prerequisites

  • An AgentPost account with an API key (prefix ap_sk_)
  • Node.js 18+ (for TypeScript SDK) or Python 3.8+ (for Python SDK), or curl for direct API access

Install the SDK

npm install agentpost
pip install agentpost

No installation needed. You can use curl from any terminal.

Set your API key as an environment variable:

export AGENTPOST_API_KEY="ap_sk_your_api_key_here"

Step 1: Initialize the client

import AgentPost from 'agentpost';

const client = new AgentPost({
  apiKey: 'ap_sk_your_api_key_here',
});
from agentpost import AgentPost

client = AgentPost(api_key="ap_sk_your_api_key_here")

All cURL examples use the $AGENTPOST_API_KEY environment variable set above.

Step 2: Create an inbox

Create an inbox to get a unique email address your agent can use to send and receive messages.

const inbox = await client.inboxes.create({
  username: 'support',
  display_name: 'AcmeCo Support',
});

console.log(`Inbox created: ${inbox.email}`);
// => Inbox created: support-a1b2c3@shared.agent-post.dev
inbox = client.inboxes.create(
    username="support",
    display_name="AcmeCo Support",
)

print(f"Inbox created: {inbox.email}")
# => Inbox created: support-a1b2c3@shared.agent-post.dev
curl -X POST https://api.agent-post.dev/api/v1/inboxes \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "support",
    "display_name": "AcmeCo Support"
  }'

Response:

{
  "id": "inb_abc123",
  "email": "support-a1b2c3@shared.agent-post.dev",
  "username": "support",
  "display_name": "AcmeCo Support",
  "domain": "shared.agent-post.dev",
  "created_at": "2026-03-08T10:30:00.000Z"
}

Username generation

The username you provide becomes a prefix. AgentPost appends a short random suffix to ensure uniqueness, producing an address like support-a1b2c3@shared.agent-post.dev. For a clean address like support@yourdomain.com, set up a custom domain.

Step 3: Send an email

Send a message from your new inbox.

const message = await client.messages.send(inbox.id, {
  to: [{ email: 'alice@example.com', name: 'Alice' }],
  subject: 'Your order has shipped',
  text_body: 'Hi Alice, your order #4821 has shipped and will arrive by Friday.',
  html_body: '<p>Hi Alice, your order <strong>#4821</strong> has shipped and will arrive by Friday.</p>',
});

console.log(`Message sent: ${message.id}`);
message = client.messages.send(
    inbox_id=inbox.id,
    to=[{"email": "alice@example.com", "name": "Alice"}],
    subject="Your order has shipped",
    text_body="Hi Alice, your order #4821 has shipped and will arrive by Friday.",
    html_body="<p>Hi Alice, your order <strong>#4821</strong> has shipped and will arrive by Friday.</p>",
)

print(f"Message sent: {message.id}")
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": "alice@example.com", "name": "Alice"}],
    "subject": "Your order has shipped",
    "text_body": "Hi Alice, your order #4821 has shipped and will arrive by Friday.",
    "html_body": "<p>Hi Alice, your order <strong>#4821</strong> has shipped and will arrive by Friday.</p>"
  }'

Response:

{
  "id": "msg_def456",
  "inbox_id": "inb_abc123",
  "direction": "outbound",
  "subject": "Your order has shipped",
  "to_addresses": [{"email": "alice@example.com", "name": "Alice"}],
  "thread_id": "thr_ghi789",
  "created_at": "2026-03-08T10:31:00.000Z"
}

Step 4: Check for received messages

List recent messages in your inbox to see inbound replies.

const messages = await client.messages.list(inbox.id, {
  direction: 'inbound',
});

for (const msg of messages.data) {
  console.log(`From: ${msg.from_address.email}`);
  console.log(`Subject: ${msg.subject}`);
  console.log(`Preview: ${msg.extracted_text?.slice(0, 100)}`);
  console.log('---');
}
messages = client.messages.list(
    inbox_id=inbox.id,
    direction="inbound",
)

for msg in messages.data:
    print(f"From: {msg.from_address['email']}")
    print(f"Subject: {msg.subject}")
    print(f"Preview: {msg.extracted_text[:100] if msg.extracted_text else ''}")
    print("---")
curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123/messages?direction=inbound" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Response:

{
  "data": [
    {
      "id": "msg_xyz999",
      "direction": "inbound",
      "subject": "Re: Your order has shipped",
      "from_address": {"email": "alice@example.com", "name": "Alice"},
      "extracted_text": "Thanks for the update! Can I get a tracking number?",
      "thread_id": "thr_ghi789",
      "created_at": "2026-03-08T11:15:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "msg_xyz999",
    "has_more": false
  }
}

Step 5: Reply to a message

Reply to a received message to continue the conversation thread.

const reply = await client.messages.reply('msg_xyz999', {
  text_body: 'Hi Alice, your tracking number is AP-2026-4821-EXPRESS. You can track it at https://track.example.com/AP-2026-4821-EXPRESS',
  html_body: '<p>Hi Alice, your tracking number is <strong>AP-2026-4821-EXPRESS</strong>. <a href="https://track.example.com/AP-2026-4821-EXPRESS">Track your package</a>.</p>',
});

console.log(`Reply sent in thread: ${reply.thread_id}`);
reply = client.messages.reply(
    message_id="msg_xyz999",
    text_body="Hi Alice, your tracking number is AP-2026-4821-EXPRESS. You can track it at https://track.example.com/AP-2026-4821-EXPRESS",
    html_body='<p>Hi Alice, your tracking number is <strong>AP-2026-4821-EXPRESS</strong>. <a href="https://track.example.com/AP-2026-4821-EXPRESS">Track your package</a>.</p>',
)

print(f"Reply sent in thread: {reply.thread_id}")
curl -X POST https://api.agent-post.dev/api/v1/messages/msg_xyz999/reply \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text_body": "Hi Alice, your tracking number is AP-2026-4821-EXPRESS.",
    "html_body": "<p>Hi Alice, your tracking number is <strong>AP-2026-4821-EXPRESS</strong>.</p>"
  }'

What's next?

You have created an inbox, sent an email, checked for replies, and responded -- the core email lifecycle for an AI agent.

Explore further:

Introduction

Architecture, core concepts, and authentication model

Inboxes

Email addresses that your agents use to send and receive messages

On this page

PrerequisitesInstall the SDKStep 1: Initialize the clientStep 2: Create an inboxStep 3: Send an emailStep 4: Check for received messagesStep 5: Reply to a messageWhat's next?