Inboxes

An inbox is an email address. Create one, and your agent can send and receive at that address. Each inbox can have its own webhook, extraction schema, and display name.

Create an inbox

The simplest way — Commune auto-assigns a domain:

const inbox = await commune.inboxes.create({
  localPart: 'support',
});
// → support@agents.yourdomain.com

inbox = client.inboxes.create(local_part="support")
# → support@agents.yourdomain.com

create_inbox(local_part="support")

curl -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{"local_part": "support"}'

With full options

const inbox = await commune.inboxes.create({
  domainId: 'domain_id',
  localPart: 'billing',
  agent: { name: 'Billing Agent' },
  webhook: {
    endpoint: 'https://your-server.com/webhook',
    events: ['inbound'],
  },
});

inbox = client.inboxes.create(
    local_part="billing",
    domain_id="domain_id",
    name="Billing Agent",
    webhook={"endpoint": "https://your-server.com/webhook"},
)

create_inbox(
  local_part="billing",
  domain_id="domain_id",
  name="Billing Agent",
  display_name="Acme Billing",
  webhook_endpoint="https://your-server.com/webhook"
)

curl -X POST https://api.commune.email/v1/inboxes \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "billing",
    "domain_id": "domain_id",
    "name": "Billing Agent",
    "display_name": "Acme Billing",
    "webhook": {
      "endpoint": "https://your-server.com/webhook",
      "events": ["inbound"]
    }
  }'

Parameters

Parameter	Type	Required	Description
`local_part`	`string`	Yes	The part before `@` (e.g., `support` → support@domain.com)
`domain_id`	`string`	No	Domain to create under. Auto-resolved if omitted.
`name`	`string`	No	Agent name (used as display name fallback)
`display_name`	`string`	No	Sender name shown in email clients (e.g., “Acme Support”)
`webhook`	`object`	No	Webhook config: `{ endpoint, events? }`
`status`	`string`	No	Initial status

Response

{
  "data": {
    "id": "inbox_f7a2b3c4",
    "localPart": "support",
    "displayName": "Acme Support",
    "agent": { "name": "Support Agent" },
    "webhook": {
      "endpoint": "https://your-server.com/webhook",
      "events": ["inbound"]
    },
    "domain_id": "d_abc123",
    "domain_name": "agents.yourdomain.com",
    "createdAt": "2026-02-14T10:00:00Z"
  }
}

Display names

When display_name is set, outbound emails appear as:

"Acme Support" <support@yourdomain.com>

instead of just support@yourdomain.com. This follows RFC 5322 and renders properly in Gmail, Outlook, and Apple Mail.

List inboxes

// All inboxes across all domains
const allInboxes = await commune.inboxes.list();

// Inboxes for a specific domain
const domainInboxes = await commune.inboxes.list('domain_id');

# All inboxes
all_inboxes = client.inboxes.list()

# Per domain
domain_inboxes = client.inboxes.list(domain_id="domain_id")

list_inboxes()                    # all
list_inboxes(domain_id="d_abc")   # per domain

# All inboxes
curl "https://api.commune.email/v1/inboxes" \
  -H "Authorization: Bearer comm_..."

# Per domain
curl "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes" \
  -H "Authorization: Bearer comm_..."

Response

{
  "data": [
    {
      "id": "inbox_f7a2b3c4",
      "localPart": "support",
      "displayName": "Acme Support",
      "agent": { "name": "Support Agent" },
      "webhook": { "endpoint": "https://..." },
      "domain_id": "d_abc123",
      "domain_name": "agents.yourdomain.com",
      "createdAt": "2026-02-14T10:00:00Z"
    }
  ]
}

Get inbox details

const inbox = await commune.inboxes.get('domain_id', 'inbox_id');

inbox = client.inboxes.get(domain_id="domain_id", inbox_id="inbox_id")

curl "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID" \
  -H "Authorization: Bearer comm_..."

Update an inbox

const updated = await commune.inboxes.update('domain_id', 'inbox_id', {
  webhook: {
    endpoint: 'https://new-server.com/webhook',
    events: ['inbound'],
  },
});

updated = client.inboxes.update(
    domain_id="domain_id",
    inbox_id="inbox_id",
    webhook={"endpoint": "https://new-server.com/webhook"},
)

curl -X PUT "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID" \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "endpoint": "https://new-server.com/webhook",
      "events": ["inbound"]
    }
  }'

Updatable fields

Field	Type	Description
`local_part`	`string`	Change the email prefix
`webhook`	`object`	Update webhook config
`status`	`string`	Set inbox status

Delete an inbox

await commune.inboxes.remove('domain_id', 'inbox_id');

client.inboxes.remove(domain_id="domain_id", inbox_id="inbox_id")

delete_inbox(domain_id="domain_id", inbox_id="inbox_id")

curl -X DELETE "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID" \
  -H "Authorization: Bearer comm_..."

Deleting an inbox is permanent. All webhook configurations are removed. Historical messages and threads remain accessible.

Set up a webhook

Configure real-time notifications when emails arrive at an inbox:

await commune.inboxes.setWebhook('domain_id', 'inbox_id', {
  endpoint: 'https://your-server.com/webhook/email',
  events: ['inbound'],
});

client.inboxes.set_webhook(
    domain_id="domain_id",
    inbox_id="inbox_id",
    endpoint="https://your-server.com/webhook/email",
)

curl -X PUT "https://api.commune.email/v1/domains/DOMAIN_ID/inboxes/INBOX_ID" \
  -H "Authorization: Bearer comm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "endpoint": "https://your-server.com/webhook/email",
      "events": ["inbound"]
    }
  }'

See Webhooks for the full payload format and delivery guarantees.

Inbox object

Field	Type	Description
`id`	`string`	Unique inbox ID
`localPart`	`string`	Email prefix (before `@`)
`address`	`string`	Full email address
`displayName`	`string \| null`	Sender name for outbound emails
`agent`	`object \| null`	Agent metadata: `{ id?, name?, metadata? }`
`webhook`	`object \| null`	Webhook config: `{ endpoint, events?, secret? }`
`extractionSchema`	`object \| null`	Structured extraction config
`createdAt`	`string`	ISO creation timestamp
`status`	`string`	Inbox status

Limits

Tier	Max inboxes
Free	3
Pro	25
Business	100
Enterprise	Unlimited

What’s next?

Messages

Send emails and list messages from your inboxes.

Webhooks

Receive real-time notifications when emails arrive.

Structured Extraction

Automatically extract structured data from inbound emails.

Domains

Add a custom domain for branded email addresses.

Get Started

SDKs

Email

Commune OAuth

Phone & SMS

Security

Integrations

Examples

Community

Create an inbox

With full options

Parameters

Response

Display names

List inboxes

Response

Get inbox details

Update an inbox

Updatable fields

Delete an inbox

Set up a webhook

Inbox object

Limits

What’s next?

Messages

Webhooks

Structured Extraction

Domains

​Create an inbox

​With full options

​Parameters

​Response

​Display names

​List inboxes

​Response

​Get inbox details

​Update an inbox

​Updatable fields

​Delete an inbox

​Set up a webhook

​Inbox object

​Limits

​What’s next?

Messages

Webhooks

Structured Extraction

Domains

Create an inbox

With full options

Parameters

Response

Display names

List inboxes

Response

Get inbox details

Update an inbox

Updatable fields

Delete an inbox

Set up a webhook

Inbox object

Limits

What’s next?