Messages

Send and receive emails programmatically through your inboxes.

Send an Email

Send an email from an inbox:

const message = await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  subject: 'Welcome to Myxara!',
  html: '<h1>Hello!</h1><p>Your AI agent is ready.</p>',
  text: 'Hello! Your AI agent is ready.'
})

console.log(message.id)
// → msg_abc123

console.log(message.status)
// → sent

Basic Parameters

Parameter	Type	Required	Description
to	string	Yes	Recipient email address
subject	string	Yes	Email subject line
html	string	No*	HTML email body
text	string	No*	Plain text email body

* At least one of html or text is required

HTML + Text

Always include both html and text versions. Email clients will choose the best format they support, improving deliverability.

With CC and BCC

Send to multiple recipients:

await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  cc: '[email protected]',
  bcc: '[email protected]',
  subject: 'Project Update',
  html: '<p>Here is the latest update...</p>',
  text: 'Here is the latest update...'
})

Email Threading

Reply to an existing email:

await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  subject: 'Re: Your inquiry',
  html: '<p>Thanks for reaching out...</p>',
  text: 'Thanks for reaching out...',
  in_reply_to: 'msg_xyz789',  // Original message ID
  references: ['msg_xyz789']   // Thread reference
})

Threading Support

Using in_reply_to and references ensures replies appear in the correct conversation thread in email clients like Gmail and Outlook.

Custom Headers

Add custom email headers:

await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  subject: 'Order Confirmation',
  html: '<p>Your order has been confirmed.</p>',
  text: 'Your order has been confirmed.',
  headers: {
    'X-Order-ID': 'order_12345',
    'X-Customer-ID': 'cust_67890',
    'X-Priority': 'High'
  }
})

With Metadata

Store custom data with the message:

await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  subject: 'Support Ticket #1234',
  html: '<p>We received your support request...</p>',
  text: 'We received your support request...',
  metadata: {
    ticket_id: '1234',
    priority: 'high',
    assigned_to: 'agent_42'
  }
})

List Messages

Get messages from an inbox:

const response = await client.inboxes.messages(inboxId).list({
  direction: 'in',  // 'in' for received, 'out' for sent
  limit: 20,
  offset: 0
})

for (const message of response.data) {
  console.log(`From: ${message.from}`)
  console.log(`Subject: ${message.subject}`)
  console.log(`Body: ${message.text}`)
  console.log('---')
}

console.log(`Total messages: ${response.total}`)

Filter by Direction

// Get received emails only
const received = await client.inboxes.messages(inboxId).list({
  direction: 'in'
})

// Get sent emails only
const sent = await client.inboxes.messages(inboxId).list({
  direction: 'out'
})

// Get all emails
const all = await client.inboxes.messages(inboxId).list()

Pagination

// Get first page of received emails
const firstPage = await client.inboxes.messages(inboxId).list({
  direction: 'in',
  limit: 10,
  offset: 0
})

// Get next page
if (firstPage.has_more) {
  const nextPage = await client.inboxes.messages(inboxId).list({
    direction: 'in',
    limit: 10,
    offset: 10
  })
}

Get a Single Message

Retrieve a specific message:

const message = await client.inboxes.messages(inboxId).get('msg_abc123')

console.log(message.from)
console.log(message.to)
console.log(message.subject)
console.log(message.html)
console.log(message.text)
console.log(message.created_at)

Delete a Message

Permanently delete a message:

await client.inboxes.messages(inboxId).delete('msg_abc123')

Permanent Deletion

Deleted messages cannot be recovered. Make sure you've saved any important data first.

Message Object

A Message object contains:

{
  id: 'msg_abc123',
  inbox_id: 'inbox_xyz789',
  direction: 'in',  // 'in' or 'out'

  // Email fields
  from: '[email protected]',
  to: '[email protected]',
  cc: null,
  bcc: null,
  subject: 'Need help with setup',

  // Content
  html: '<p>I need assistance setting up...</p>',
  text: 'I need assistance setting up...',

  // Threading
  in_reply_to: null,
  references: [],
  message_id: '<[email protected]>',

  // Metadata
  headers: {
    'X-Custom-Header': 'value'
  },
  metadata: {
    ticket_id: '1234'
  },

  // Status
  status: 'delivered',  // 'sent', 'delivered', 'failed'

  // Timestamps
  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 handleCustomerEmail() {
  // Create an inbox
  const inbox = await client.inboxes.create({
    local_part: 'support',
    name: 'Support Agent'
  })

  // Send welcome email
  await client.inboxes.messages(inbox.id).send({
    to: '[email protected]',
    subject: 'Welcome to our service!',
    html: `
      <h1>Welcome!</h1>
      <p>Thanks for signing up. We're here to help.</p>
      <p>Reply to this email if you have any questions.</p>
    `,
    text: `
      Welcome!
      Thanks for signing up. We're here to help.
      Reply to this email if you have any questions.
    `,
    metadata: {
      email_type: 'welcome',
      customer_id: 'cust_123'
    }
  })

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

  // Process each message
  for (const msg of messages.data) {
    console.log(`New message from ${msg.from}`)
    console.log(`Subject: ${msg.subject}`)

    // Reply to the message
    await client.inboxes.messages(inbox.id).send({
      to: msg.from,
      subject: `Re: ${msg.subject}`,
      html: '<p>Thanks for your message. We will respond shortly.</p>',
      text: 'Thanks for your message. We will respond shortly.',
      in_reply_to: msg.id,
      references: [msg.id],
      metadata: {
        reply_to: msg.id,
        auto_reply: true
      }
    })
  }
}

handleCustomerEmail().catch(console.error)

HTML Email Best Practices

Use Tables for Layout

const html = `
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body style="margin: 0; padding: 0; font-family: Arial, sans-serif;">
  <table role="presentation" width="100%" cellpadding="0" cellspacing="0">
    <tr>
      <td style="padding: 20px;">
        <h1 style="color: #333;">Welcome!</h1>
        <p style="color: #666; line-height: 1.6;">
          Your AI agent is ready to help.
        </p>
      </td>
    </tr>
  </table>
</body>
</html>
`

await client.inboxes.messages(inboxId).send({
  to: '[email protected]',
  subject: 'Welcome',
  html,
  text: 'Welcome! Your AI agent is ready to help.'
})

Inline Styles

Email clients have limited CSS support. Always use inline styles:

// ✅ Good - inline styles
const html = '<p style="color: blue;">Hello</p>'

// ❌ Bad - external stylesheet
const html = '<link rel="stylesheet" href="style.css"><p class="blue">Hello</p>'

// ❌ Bad - style tag
const html = '<style>.blue{color:blue}</style><p class="blue">Hello</p>'

Error Handling

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

try {
  await client.inboxes.messages(inboxId).send({
    to: 'invalid-email',  // Invalid email format
    subject: 'Test',
    text: 'Test message'
  })
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation errors:', error.errors)
    // → { to: ['Invalid email address'] }
  } else if (error instanceof APIError) {
    console.error('API error:', error.message)
  }
}

TypeScript Types

import type {
  Message,
  SendMessageParams,
  ListMessagesParams,
  ListResponse
} from '@myxara/sdk-js'

const params: SendMessageParams = {
  to: '[email protected]',
  subject: 'Hello',
  html: '<p>Hello!</p>',
  text: 'Hello!'
}

const message: Message = await client.inboxes.messages(inboxId).send(params)

const response: ListResponse<Message> = await client.inboxes.messages(inboxId).list()

Next Steps

• Webhooks → - Get real-time notifications for new messages
• Examples → - See complete email automation examples
• Error Handling → - Handle email sending errors gracefully