SDK Reference

The official TypeScript/JavaScript SDK for Myxara - the easiest way to integrate email into your AI agents.

Installation

npm

npm install @myxara/sdk-js

yarn

yarn add @myxara/sdk-js

bun

bun add @myxara/sdk-js

Quick Example

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

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

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

// Send an email
await client.inboxes.messages(inbox.id).send({
  to: 'customer@example.com',
  subject: 'Hello!',
  html: '<p>Your AI agent is ready.</p>'
})

Key Features

• TypeScript First - Full type safety with IntelliSense support
• Automatic Retries - Built-in retry logic for transient failures
• Error Handling - Typed error classes for precise error handling
• Streaming Support - Efficient handling of large datasets
• Type Coercion - Automatic conversion between types (e.g., Date objects)

SDK Structure

The SDK is organized around resource-based APIs:

const client = new MyxaraClient({ apiKey: 'mx_...' })

// Inboxes
client.inboxes.create(...)
client.inboxes.list(...)
client.inboxes.get(id)
client.inboxes.update(id, ...)
client.inboxes.delete(id)

// Messages
client.inboxes.messages(inboxId).send(...)
client.inboxes.messages(inboxId).list(...)
client.inboxes.messages(inboxId).get(messageId)

// Webhooks
client.webhooks.create(...)
client.webhooks.list(...)
client.webhooks.update(id, ...)
client.webhooks.delete(id)

// API Keys
client.apiKeys.create(...)
client.apiKeys.list(...)
client.apiKeys.revoke(id)

Basic Concepts

Resources

Every API endpoint in Myxara is organized around resources:

• Inboxes - Programmatic email addresses for your AI agents
• Messages - Emails sent and received by your inboxes
• Webhooks - Real-time notifications for inbox events
• API Keys - Authentication credentials with scoped permissions

Pagination

List endpoints return paginated results:

const response = await client.inboxes.list({
  limit: 20,      // Items per page (default: 10, max: 100)
  offset: 0       // Skip N items (default: 0)
})

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

Iterating Through Pages

For large datasets, use offset-based pagination:

let offset = 0
const limit = 100

while (true) {
  const response = await client.inboxes.list({ limit, offset })

  for (const inbox of response.data) {
    // Process inbox...
  }

  if (!response.has_more) break
  offset += limit
}

Error Handling

The SDK throws typed errors for different failure scenarios:

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

try {
  await client.inboxes.create(...)
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid API key
    console.error('Authentication failed')
  } else if (error instanceof RateLimitError) {
    // Too many requests
    console.log(`Retry after ${error.retryAfter}s`)
  } else if (error instanceof ValidationError) {
    // Invalid request data
    console.error('Validation errors:', error.errors)
  } else if (error instanceof APIError) {
    // Other API errors
    console.error(`API error: ${error.message}`)
  }
}

Learn more about error handling →

Request Options

Customize individual requests with options:

// Override timeout for specific request
await client.inboxes.list({}, {
  timeout: 60000  // 60 seconds
})

// Add custom headers
await client.inboxes.create({...}, {
  headers: {
    'X-Custom-Header': 'value'
  }
})

// Disable automatic retries
await client.inboxes.list({}, {
  maxRetries: 0
})

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import type {
  Inbox,
  Message,
  Webhook,
  CreateInboxParams,
  SendMessageParams
} from '@myxara/sdk-js'

// Type-safe parameters
const params: CreateInboxParams = {
  local_part: 'support',
  name: 'Support Agent'
}

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

// IntelliSense for all properties
console.log(inbox.address)  // TypeScript knows this exists

Enable Strict Mode

For the best experience, enable TypeScript strict mode in your tsconfig.json:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Next Steps

Client Configuration →

Learn about all client options including retries, timeouts, and custom base URLs

Inboxes →

Create and manage email addresses for your AI agents

Messages →

Send and receive emails programmatically

Webhooks →

Get real-time notifications when emails arrive

Error Handling →

Handle errors gracefully with typed error classes