Inboxes

An inbox is an email address that can send and receive messages. Every email interaction in AgentPost flows through an inbox. Agents create inboxes programmatically, and each inbox gets a unique email address.

Key properties

Email address format

On the shared domain, inbox addresses follow the pattern:

{username}-{random}@shared.agent-post.dev

The random suffix ensures uniqueness across all organizations. If you provide username: "support", the resulting address might be support-a1b2c3@shared.agent-post.dev.

On a custom domain, the address uses your domain directly:

{username}@yourdomain.com

Creating inboxes

import AgentPost from 'agentpost';

const client = new AgentPost({ apiKey: 'ap_sk_...' });

const inbox = await client.inboxes.create({
  username: 'deploy-alerts',
  display_name: 'Deployment Alerts',
});

from agentpost import AgentPost

client = AgentPost(api_key="ap_sk_...")

inbox = client.inboxes.create(
    username="deploy-alerts",
    display_name="Deployment Alerts",
)

curl -X POST https://api.agent-post.dev/api/v1/inboxes \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "deploy-alerts", "display_name": "Deployment Alerts"}'

Idempotent creation with client_id

Use client_id to safely retry inbox creation without creating duplicates. If an inbox with the same client_id already exists, the existing inbox is returned instead of creating a new one.

// Safe to call multiple times -- same inbox returned each time
const inbox = await client.inboxes.create({
  username: 'ticket-routing',
  display_name: 'Ticket Router',
  client_id: 'ticket-router-prod-v1',
});

inbox = client.inboxes.create(
    username="ticket-routing",
    display_name="Ticket Router",
    client_id="ticket-router-prod-v1",
)

curl -X POST https://api.agent-post.dev/api/v1/inboxes \
  -H "Authorization: Bearer $AGENTPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "ticket-routing", "display_name": "Ticket Router", "client_id": "ticket-router-prod-v1"}'

Listing and retrieving inboxes

// List all inboxes with cursor-based pagination
const inboxes = await client.inboxes.list({ limit: 20 });

// Get a specific inbox
const inbox = await client.inboxes.get('inb_abc123');

# List all inboxes
inboxes = client.inboxes.list(limit=20)

# Get a specific inbox
inbox = client.inboxes.get("inb_abc123")

# List inboxes
curl "https://api.agent-post.dev/api/v1/inboxes?limit=20" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

# Get a specific inbox
curl "https://api.agent-post.dev/api/v1/inboxes/inb_abc123" \
  -H "Authorization: Bearer $AGENTPOST_API_KEY"

Shared domains vs custom domains

For production use, custom domains are recommended for better deliverability and professional appearance.

Inbox lifecycle

1. Create -- Call POST /api/v1/inboxes to create a new inbox
2. Active -- Inbox can send and receive messages
3. Paused -- Sending can be paused (e.g., due to domain issues or rate limits). Receiving continues.
4. Update -- Update display name or other properties via PATCH /api/v1/inboxes/:id
5. Delete -- Delete the inbox via DELETE /api/v1/inboxes/:id. Messages are retained.

Username rules

• Usernames must be between 1 and 64 characters
• Allowed characters: lowercase letters, digits, hyphens, dots, underscores
• Cannot start or end with a hyphen, dot, or underscore
• Cannot contain consecutive dots or hyphens

Relationships

• Messages belong to an inbox. Each message has an inbox_id.
• Threads are scoped to an inbox. List threads for a specific inbox via GET /api/v1/inboxes/:id/threads.
• Drafts belong to an inbox. Create drafts for an inbox via POST /api/v1/inboxes/:id/drafts.
• Domains determine the domain portion of inbox email addresses.
• Environments scope inboxes for tenant isolation.

Tips

• Use client_id for any inbox your agent creates on startup to avoid duplicates after restarts
• Create dedicated inboxes per purpose (alerts, support, notifications) rather than multiplexing a single inbox
• Monitor the send_paused field -- it indicates delivery issues that may need attention
• Inbox email addresses are immutable after creation. To change an address, create a new inbox.