Inboxes

Create and manage email addresses for your AI agents.

What is an Inbox?

An inbox is a programmatic email address that can send and receive emails. Each inbox gets a unique address like [email protected] that works immediately - no DNS configuration required.

Create an Inbox

const inbox = await client.inboxes.create({
  local_part: 'support',
  name: 'AI Support Agent'
})

console.log(inbox.address)
// → [email protected]

console.log(inbox.id)
// → inbox_abc123

Parameters

Parameter	Type	Required	Description
local_part	string	Yes	The part before @ (e.g., "support")
name	string	Yes	Human-readable name for the inbox
description	string	No	Optional description
metadata	object	No	Custom key-value data

Choosing a local_part

• Use lowercase letters, numbers, dots, and hyphens
• Must start and end with alphanumeric character
• Examples: support, sales, agent-001, team.ai

With Metadata

Store custom data with your inbox:

const inbox = await client.inboxes.create({
  local_part: 'sales-agent-01',
  name: 'Sales Agent 01',
  metadata: {
    region: 'us-west',
    team: 'enterprise',
    agent_id: 'agent_xyz'
  }
})

// Access metadata later
console.log(inbox.metadata.region)
// → us-west

List Inboxes

Get all inboxes with pagination:

const response = await client.inboxes.list({
  limit: 20,
  offset: 0
})

console.log(response.data)        // Array of inboxes
console.log(response.total)       // Total count
console.log(response.has_more)    // More pages available?

Pagination Example

// Get first page
let response = await client.inboxes.list({ limit: 10, offset: 0 })

for (const inbox of response.data) {
  console.log(inbox.address)
}

// Get next page if available
if (response.has_more) {
  response = await client.inboxes.list({ limit: 10, offset: 10 })
}

Default Pagination

• Default limit: 10
• Maximum limit: 100
• Default offset: 0

Get a Single Inbox

Retrieve an inbox by ID:

const inbox = await client.inboxes.get('inbox_abc123')

console.log(inbox.address)
console.log(inbox.name)
console.log(inbox.created_at)

Update an Inbox

Change the name, description, or metadata:

const updated = await client.inboxes.update('inbox_abc123', {
  name: 'Updated Support Agent',
  description: 'Handles tier-1 support tickets',
  metadata: {
    version: '2.0',
    upgraded_at: new Date().toISOString()
  }
})

console.log(updated.name)
// → Updated Support Agent

Can't Change Address

You cannot change the local_part (email address) after creation. If you need a different address, create a new inbox.

Delete an Inbox

Permanently delete an inbox and all its messages:

await client.inboxes.delete('inbox_abc123')

This is Permanent

Deleting an inbox:

• Deletes all messages in the inbox
• Stops receiving emails at that address
• Cannot be undone

Make sure you've exported any important data first!

Working with Messages

Access messages for a specific inbox:

const inbox = await client.inboxes.get('inbox_abc123')

// Send a message
await client.inboxes.messages(inbox.id).send({
  to: '[email protected]',
  subject: 'Hello!',
  html: '<p>Your AI agent is ready.</p>'
})

// List received messages
const messages = await client.inboxes.messages(inbox.id).list({
  direction: 'in',
  limit: 10
})

for (const msg of messages.data) {
  console.log(msg.from)
  console.log(msg.subject)
}

Learn more about messages →

Response Object

The Inbox object contains:

{
  id: 'inbox_abc123',
  local_part: 'support',
  address: '[email protected]',
  name: 'AI Support Agent',
  description: 'Handles customer inquiries',
  metadata: {
    team: 'support',
    region: 'us-east'
  },
  created_at: '2025-01-15T10:30:00Z',
  updated_at: '2025-01-15T10:30:00Z'
}

Complete Example

import { MyxaraClient } from '@myxara/sdk-js'

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!
})

async function setupInboxes() {
  // Create multiple inboxes for different purposes
  const support = await client.inboxes.create({
    local_part: 'support',
    name: 'Support Agent',
    metadata: { type: 'support', priority: 'high' }
  })

  const sales = await client.inboxes.create({
    local_part: 'sales',
    name: 'Sales Agent',
    metadata: { type: 'sales', priority: 'high' }
  })

  const marketing = await client.inboxes.create({
    local_part: 'marketing',
    name: 'Marketing Agent',
    metadata: { type: 'marketing', priority: 'low' }
  })

  console.log('Created inboxes:')
  console.log(`- ${support.address}`)
  console.log(`- ${sales.address}`)
  console.log(`- ${marketing.address}`)

  // List all inboxes
  const response = await client.inboxes.list()
  console.log(`\nTotal inboxes: ${response.total}`)

  // Update an inbox
  await client.inboxes.update(support.id, {
    description: 'Primary customer support channel'
  })

  // Delete old inbox
  // await client.inboxes.delete('inbox_old123')
}

setupInboxes().catch(console.error)

Error Handling

import { ValidationError, APIError } from '@myxara/sdk-js'

try {
  const inbox = await client.inboxes.create({
    local_part: 'support',
    name: 'Support'
  })
} catch (error) {
  if (error instanceof ValidationError) {
    // Handle validation errors
    console.error('Invalid parameters:', error.errors)
  } else if (error instanceof APIError) {
    if (error.status === 409) {
      // Inbox with this local_part already exists
      console.error('Inbox already exists')
    } else {
      console.error('API error:', error.message)
    }
  }
}

TypeScript Types

import type {
  Inbox,
  CreateInboxParams,
  UpdateInboxParams,
  ListInboxesParams,
  ListResponse
} from '@myxara/sdk-js'

const params: CreateInboxParams = {
  local_part: 'support',
  name: 'Support Agent',
  metadata: {
    custom_field: 'value'
  }
}

const inbox: Inbox = await client.inboxes.create(params)

const response: ListResponse<Inbox> = await client.inboxes.list()

Next Steps

• Messages → - Send and receive emails
• Webhooks → - Get real-time notifications
• Examples → - See complete code examples