Client Configuration

Configure the Myxara SDK client to match your application's needs.

Basic Setup

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

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

Keep API Keys Secret

Never hardcode API keys in your source code. Always use environment variables or a secrets manager.

Configuration Options

API Key

Required. Your Myxara API key for authentication.

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

Base URL

Override the API base URL for self-hosted instances:

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  baseUrl: 'http://localhost:8787'
})

Default Base URL

The default base URL is https://api.myxara.ai. Only change this if you're self-hosting Myxara.

Timeout

Set request timeout in milliseconds (default: 60000ms / 1 minute):

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  timeout: 30000  // 30 seconds
})

Max Retries

Configure automatic retry behavior for failed requests (default: 2):

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  maxRetries: 5  // Retry up to 5 times
})

The SDK automatically retries:

• Network errors
• 5xx server errors
• 429 rate limit errors (with exponential backoff)

Retry Strategy

The SDK uses exponential backoff with jitter:

• 1st retry: ~1 second
• 2nd retry: ~2 seconds
• 3rd retry: ~4 seconds
• And so on...

Custom Headers

Add custom headers to all requests:

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  defaultHeaders: {
    'X-Custom-Header': 'value',
    'X-App-Version': '1.0.0'
  }
})

Fetch Implementation

Provide a custom fetch implementation:

import fetch from 'node-fetch'

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

When to Use This

This is useful for:

• Node.js < 18 (no native fetch)
• Custom proxy configurations
• Request/response interceptors
• Testing with mocked fetch

Complete Example

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

const client = new MyxaraClient({
  // Required
  apiKey: process.env.MYXARA_API_KEY!,

  // Optional configurations
  baseUrl: process.env.MYXARA_BASE_URL || 'https://api.myxara.ai',
  timeout: 60000,
  maxRetries: 3,
  defaultHeaders: {
    'X-App-Name': 'My AI Agent',
    'X-App-Version': '1.0.0'
  }
})

export default client

Environment-Based Configuration

Use different configurations for development and production:

const isDevelopment = process.env.NODE_ENV === 'development'

const client = new MyxaraClient({
  apiKey: process.env.MYXARA_API_KEY!,
  baseUrl: isDevelopment
    ? 'http://localhost:8787'
    : 'https://api.myxara.ai',
  timeout: isDevelopment ? 10000 : 60000,
  maxRetries: isDevelopment ? 0 : 3  // No retries in dev
})

Per-Request Options

Override client configuration for specific requests:

// Override timeout for a slow operation
await client.inboxes.list({}, {
  timeout: 120000  // 2 minutes
})

// Disable retries for a specific request
await client.inboxes.create({...}, {
  maxRetries: 0
})

// Add request-specific headers
await client.inboxes.list({}, {
  headers: {
    'X-Request-ID': crypto.randomUUID()
  }
})

Testing Configuration

For unit tests, use a separate test client:

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

// Test client with short timeouts and no retries
export const testClient = new MyxaraClient({
  apiKey: 'mx_test_key',
  baseUrl: 'http://localhost:8787',
  timeout: 5000,
  maxRetries: 0
})

TypeScript Types

import type { MyxaraClientOptions } from '@myxara/sdk-js'

const options: MyxaraClientOptions = {
  apiKey: process.env.MYXARA_API_KEY!,
  timeout: 30000,
  maxRetries: 2
}

const client = new MyxaraClient(options)

Validation

The client validates configuration on initialization:

// ❌ Throws error - missing API key
const client = new MyxaraClient({})

// ❌ Throws error - invalid timeout
const client = new MyxaraClient({
  apiKey: 'mx_key',
  timeout: -1000
})

// ❌ Throws error - invalid maxRetries
const client = new MyxaraClient({
  apiKey: 'mx_key',
  maxRetries: -1
})

Next Steps

• Inboxes → - Create and manage email addresses
• Messages → - Send and receive emails
• Error Handling → - Handle errors gracefully