@outofscope/sdk-email

Lightweight TypeScript SDK that wraps the OutOfScope Email API. It exposes a small EmailClient with convenience methods for the /email/* gateway endpoints and keeps fetch pluggable for browser, Node.js, or serverless runtimes.

Installation

The SDK ships as plain TypeScript. Install it with your preferred package manager:

npm install @outofscope/sdk-email

If your environment does not provide a global fetch, pass one in when you create the client (for example from node-fetch or undici).

Usage

import { createEmailClient } from '@outofscope/sdk-email';

const email = createEmailClient({ baseUrl: 'https://api.example.com/email' });

// List all threads for a tenant
const threads = await email.listThreads('tenant-123');

// Retrieve a single thread with messages
const thread = await email.getThread('tenant-123', 'thread-abc');

// Send a message (creates a thread when threadId is omitted)
await email.sendMessage({
  tenantId: 'tenant-123',
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Welcome!',
  text: 'Hello world',
});

API

createEmailClient(options?: { baseUrl?: string; fetchImpl?: typeof fetch })

Creates a reusable client. baseUrl should point to the email gateway root (e.g. https://api.example.com/email). fetchImpl lets you supply any Fetch-compatible implementation.

EmailClient.listThreads(tenantId: string): Promise<EmailThreadSummary[]>

Calls GET {baseUrl}/threads?tenantId=... and returns the list of threads for the tenant.

EmailClient.getThread(tenantId: string, threadId: string): Promise<EmailThread>

Calls GET {baseUrl}/thread/:id?tenantId=... and returns thread metadata plus its messages.

EmailClient.sendMessage(payload: SendMessagePayload): Promise<{ ok: boolean; threadId: string; messageId: string; }>

Calls POST {baseUrl}/send with the payload to queue an email. Responds with identifiers and always sets ok: true on success.

Error handling

Non-2xx responses throw an ApiError that includes the HTTP status and any parsed error body. Wrap calls in your own error handling to translate messages for users.

Development

• Build: npm run build
• Clean: npm run clean

Publishing produces compiled output in dist/ with bundled type declarations.