@inbox-api/client

Shared HTTP client and TypeScript types for the Inbox API. Used internally by @inbox-api/mcp and @inbox-api/cli.

Installation

npm install @inbox-api/client

Usage

import { ApiClient, ApiError } from '@inbox-api/client';
import type { AccountInfo, MessageListResponse, PagedResult } from '@inbox-api/client';

const client = new ApiClient('https://api.inbox-api.com', 'cw_your_token');

// List email accounts (paginated)
const accounts = await client.get<PagedResult<AccountInfo>>('/api/email/accounts', {
  pageSize: '100',
});

// List messages with filters and sorting
const messages = await client.get<MessageListResponse>('/api/email/messages', {
  accountId: 'some-uuid',
  isRead: 'false',
  sort: 'date',
  page: '1',
  pageSize: '10',
});

// Search messages with BM25 ranking
const results = await client.get<MessageListResponse>('/api/email/messages', {
  q: 'invoice from:[email protected]',
  sort: 'relevance',
  pageSize: '10',
});

// Send an email
await client.post('/api/email/send', {
  accountId: 'some-uuid',
  to: [{ email: '[email protected]', name: 'Recipient' }],
  subject: 'Hello',
  textBody: 'Message body here.',
});

// Error handling
try {
  await client.get('/api/email/messages/invalid-id');
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.status);  // HTTP status code (e.g. 404)
    console.error(err.message); // "API error 404: Not found"
  }
}

API

ApiClient

new ApiClient(baseUrl: string, token: string)

| Method | Signature | Description | |--------|-----------|-------------| | get | get<T>(path, params?) | GET request with optional query parameters | | post | post<T>(path, body?) | POST request with optional JSON body | | put | put<T>(path, body?) | PUT request with optional JSON body | | patch | patch<T>(path, body?) | PATCH request with optional JSON body | | delete | delete<T>(path) | DELETE request |

All methods return Promise<T> and throw ApiError on non-2xx responses.

ApiError

class ApiError extends Error {
  readonly status: number;
}

Types

Entity types:

• AccountInfo — email account summary (id, displayName, emailAddress, provider, messageCount, unreadCount)
• MessageDto — email message metadata (id, subject, from/to/cc, dates, flags)
• MessageBody — email content (textBody, htmlBody)
• ThreadDetailDto — conversation thread with nested messages
• DraftDto — draft email (id, accountId, subject, body, createdAt)
• FolderDto — mailbox folder (id, name, fullPath, counts)
• AddressDto — email address with optional display name
• AttachmentDto — attachment metadata (fileName, mimeType, size, isInline)
• ContactDto — email contact with frequency and last seen date
• WebhookDto — webhook subscription (url, events, payloadLevel, isActive)
• WebhookDeliveryDto — webhook delivery status

Request types:

• SendEmailRequest, ReplyRequest, ForwardEmailRequest
• CreateDraftRequest, UpdateDraftRequest
• MoveMessageRequest, UpdateMessageFlagsRequest
• CreateWebhookRequest, UpdateWebhookRequest

Response types:

• PagedResult<T> — generic paged response (items, totalCount, page, pageSize)
• MessageListResponse — alias for PagedResult<MessageDto>
• DigestResponse — email digest with per-account summaries
• AccountHealthDto — IMAP connection health status
• BatchOperationResponse — batch operation results

Prerequisites

• Node.js >= 18 (uses built-in fetch)

Development

# Build
npm run build

# Watch mode
npm run dev

This package has no runtime dependencies. It uses the built-in fetch API available in Node.js 18+.

License

MIT