Mailboxes

Create and manage project mailboxes that route email into rooms and queues.

Mailboxes are project-level email addresses that route inbound mail into rooms. They belong at the project level because the address belongs to the project, even though the work is delivered to a queue in a specific room.

Use mailboxes when an agent listens on a mail: channel, or when you want inbound email to land in a queue that something in the room already consumes.

Create a mailbox

meshagent mailbox create \
  --address [e-mail] \
  --room customer-support \
  --queue support-inbox

This creates a project mailbox and routes messages sent to [e-mail] into the support-inbox queue in the customer-support room.

Inspect and manage mailboxes

meshagent mailbox list
meshagent mailbox get [e-mail]
meshagent mailbox update [e-mail] --queue escalations
meshagent mailbox delete [e-mail]

Inspect outbound delivery status

When Mailgun delivery tracking is enabled for the deployment, inspect each recipient’s current status and provider event timeline:

meshagent mailbox deliveries [e-mail]
meshagent mailbox delivery [e-mail] DELIVERY_ID
meshagent mailbox delivery-events [e-mail] DELIVERY_ID

The delivery list is newest submission first. A submission with multiple recipients has one delivery row per recipient because their outcomes and retry timelines can differ. Use --status, --recipient, or --message-id to narrow the list, and use --output json when calling the commands from a script:

meshagent mailbox deliveries [e-mail] \
  --status deferred \
  --recipient example.com \
  --output json

meshagent mailbox delivery-events [e-mail] DELIVERY_ID \
  --count 100 \
  --offset 0 \
  --output json

Delivery statuses and events

A delivery is the current rollup for one recipient. Its status is one of:

Status	Meaning
accepted	The provider accepted the message for delivery.
deferred	A delivery attempt failed temporarily and may be retried.
delivered	The provider reported successful delivery.
failed	The provider reported a permanent delivery failure.

The delivery also contains the latest provider details, including attempt_count, SMTP response codes, failure reason and description, MX host, and TLS and certificate-verification results when the provider supplies them.

Delivery events are the chronological history behind that current status. The API normalizes provider notifications into these event types:

Event type	Resulting delivery status
accepted	accepted
temporary_failed	deferred
delivered	delivered
permanent_failed	failed

Each event includes occurred_at and received_at, its resulting status, and the provider and provider event ID. When available, it also includes the attempt number, SMTP and enhanced SMTP codes, reason, description, MX host, TLS use, and certificate-verification result. Events are returned oldest first, ordered by occurred_at and then event ID.

In Studio, open the mailbox options menu and select Deliveries…. Select a delivery row to open its event timeline.

Permissions

• To create, update, or delete a mailbox for a room, you need permission to administer that room.
• To list mailboxes across the whole project, you need developer access.
• To read delivery status as a user, you need the OAuth scope mailboxes:read and the project mailbox_inventory relation. Room membership and room read access do not grant delivery visibility. Project API keys retain project-wide access.

Where to manage mailboxes

• Use MeshAgent Studio for the main UI flow.
• Use the CLI when you want quick setup or scripting.
• Use the REST API when you need programmatic mailbox management.

Related pages

• Feeds
• Process Agents Overview
• Queue API
• Quickstart
• REST API