mailboxkit

Official Node.js SDK for MailboxKit — email infrastructure for AI agents.

Installation

npm install mailboxkit

Quick Start

import { MailboxKit } from 'mailboxkit';

const mailbox = new MailboxKit('your-api-key');

// Create an inbox
const { data: inbox } = await mailbox.inboxes.create({ name: 'My Agent Inbox' });

// Send an email
const { data: message } = await mailbox.messages.send({
  inboxId: inbox.id,
  to: '[email protected]',
  subject: 'Hello from my AI agent',
  text: 'This email was sent by an AI agent using MailboxKit.',
});

// Wait for a reply (polls until a new incoming message arrives)
const { data: reply } = await mailbox.messages.waitFor(inbox.id, {
  from: '[email protected]',
  timeout: 120000, // 2 minutes
});

console.log('Got reply:', reply.text);

Authentication

Pass your API key directly or set the MAILBOXKIT_API_KEY environment variable:

// Explicit key
const mailbox = new MailboxKit('mk_live_...');

// From environment variable
const mailbox = new MailboxKit();

Configuration

const mailbox = new MailboxKit('your-api-key', {
  baseUrl: 'https://mailboxkit.com/api/v1', // default
  timeout: 30000,                            // 30s default
  maxRetries: 2,                             // default
});

Agent Self-Registration

AI agents can register themselves without pre-existing credentials:

import { MailboxKit } from 'mailboxkit';

const { data } = await MailboxKit.register({
  name: 'Acme Corp',
  email: '[email protected]',
  agentName: 'support-bot',
});

const mailbox = new MailboxKit(data.api_key);

Account Verification

After registration, your account is in restricted mode — you can only send emails to your owner's email address. To unlock full sending, verify with the OTP code sent to the owner:

// Your human shares the 6-digit code from their email
await mailbox.organization.verify({ otpCode: '123456' });

// If the code expired, request a new one
await mailbox.organization.resendVerification();

Once verified, you can send emails to anyone.

Resources

Inboxes

await mailbox.inboxes.create({ name: 'Support', domainId: '...' });
await mailbox.inboxes.list();
await mailbox.inboxes.get('inbox-id');
await mailbox.inboxes.update('inbox-id', { name: 'New Name' });
await mailbox.inboxes.delete('inbox-id');

Messages

await mailbox.messages.send({ inboxId: '...', to: '[email protected]', subject: 'Hi', text: 'Hello' });
await mailbox.messages.reply({ inboxId: '...', messageId: '...', text: 'Thanks!' });
await mailbox.messages.list('inbox-id', { direction: 'incoming', read: 'false' });
await mailbox.messages.get('inbox-id', 'message-id');
await mailbox.messages.markRead('inbox-id', 'message-id');
await mailbox.messages.search({ query: 'verification code' });
await mailbox.messages.waitFor('inbox-id', { from: '[email protected]', timeout: 60000 });

Webhooks

await mailbox.webhooks.create({ name: 'My Hook', url: 'https://...', events: ['message.received'] });
await mailbox.webhooks.list();
await mailbox.webhooks.get('webhook-id');
await mailbox.webhooks.delete('webhook-id');
await mailbox.webhooks.test('webhook-id');
await mailbox.webhooks.attempts('webhook-id');

Domains

await mailbox.domains.create({ name: 'example.com' });
await mailbox.domains.list();
await mailbox.domains.get('domain-id');
await mailbox.domains.delete('domain-id');
await mailbox.domains.verify('domain-id');
await mailbox.domains.dns('domain-id');

API Keys

await mailbox.apiKeys.create({ name: 'Agent Key' });
await mailbox.apiKeys.list();
await mailbox.apiKeys.get('key-id');
await mailbox.apiKeys.delete('key-id');

Organization

await mailbox.organization.get();

Error Handling

import { MailboxKitError } from 'mailboxkit';

try {
  await mailbox.messages.send({ ... });
} catch (err) {
  if (err instanceof MailboxKitError) {
    console.error(err.message);     // Human-readable message
    console.error(err.error);       // Machine-readable code
    console.error(err.statusCode);  // HTTP status
    console.error(err.action);      // Suggested fix
  }
}

Requirements

• Node.js 18+ (uses native fetch)
• No external dependencies

License

MIT