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

Property	Description
`id`	Unique identifier (prefix `inb_`)
`email`	Full email address (e.g., `[email protected]`)
`username`	The local part prefix you chose
`display_name`	Human-readable name shown in email headers
`domain`	Domain portion of the email address
`client_id`	Optional idempotency key for safe retries
`send_paused`	Whether outbound sending is paused

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 [email protected].

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

Feature	Shared Domain	Custom Domain
Address format	`[email protected]`	`[email protected]`
Setup required	None	DNS verification (SPF, DKIM, DMARC)
Deliverability	Good (shared reputation)	Best (your own reputation)
Branding	AgentPost domain visible	Your domain visible
Catch-all	Not available	Available

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

Inbox lifecycle

Create -- Call POST /api/v1/inboxes to create a new inbox
Active -- Inbox can send and receive messages
Paused -- Sending can be paused (e.g., due to domain issues or rate limits). Receiving continues.
Update -- Update display name or other properties via PATCH /api/v1/inboxes/:id
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.

Inboxes

On this page