> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simpleemailapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Send emails using the official type-safe SDK.

# TypeScript SDK

The `simpleemailapi` package provides a fully typed, backend-first SDK for Node.js workflows.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install simpleemailapi
  ```

  ```bash pnpm theme={null}
  pnpm add simpleemailapi
  ```

  ```bash yarn theme={null}
  yarn add simpleemailapi
  ```
</CodeGroup>

## Usage

Initialize the client with your API key and use the `client.send` method.

```typescript theme={null}
import { createClient } from 'simpleemailapi';

const client = createClient({ apiKey: 'sea_live_...' });

const result = await client.send({
  from: 'hello@yourdomain.com', // Must be verified
  to: ['recipient@example.com'],
  subject: 'Welcome aboard!',
  text: 'Thanks for signing up.', // inferred from 'body' in proto but 'text' is common alias, let's stick to proto 'body' for accuracy
  body: 'Thanks for signing up.',
  html: '<p>Thanks for signing up.</p>'
});

console.log('Email ID:', result.id);
```

<Note>
  The `from` address must belong to a domain you have [verified](/domains/introduction).
</Note>

## Client Configuration

The `createClient` function accepts the following options:

<ResponseField name="apiKey" type="string" required>
  Your API Key, starting with `sea_live_`.
</ResponseField>

<ResponseField name="baseUrl" type="string">
  API endpoint URL. Defaults to `https://api.simpleemailapi.dev`.
</ResponseField>

## arguments

The `client.send` method accepts an object with the following properties:

<ParamField body="from" type="string" required>
  Sender email address. Must be from a verified domain.
</ParamField>

<ParamField body="to" type="string[]" required>
  List of primary recipient email addresses.
</ParamField>

<ParamField body="subject" type="string" required>
  Email subject line.
</ParamField>

<ParamField body="body" type="string">
  Plain text content of the email.
</ParamField>

<ParamField body="html" type="string">
  HTML content of the email.
</ParamField>

<ParamField body="cc" type="string[]">
  List of CC recipient email addresses.
</ParamField>

<ParamField body="bcc" type="string[]">
  List of BCC recipient email addresses.
</ParamField>

<ParamField body="attachments" type="Attachment[]">
  List of files to attach.

  <Expandable title="Attachment properties">
    <ParamField body="filename" type="string" required>
      Name of the file.
    </ParamField>

    <ParamField body="contentType" type="string" required>
      MIME type (e.g., `application/pdf`).
    </ParamField>

    <ParamField body="content" type="Buffer | string" required>
      File content as a Buffer or Base64 string.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="replyTo" type="string">
  Reply to a previous email using its `id` from our response. We automatically resolve threading headers.
</ParamField>

<ParamField body="inReplyTo" type="string">
  Raw Message-ID for threading (advanced). Use `replyTo` for simpler threading with our email IDs.
</ParamField>

<ParamField body="references" type="string[]">
  List of message IDs for threading context.
</ParamField>

<ParamField body="headers" type="Record<string, string>">
  Custom headers. // Proto has `metadata`, effectively custom headers/metadata.
</ParamField>

<ParamField body="metadata" type="Record<string, string>">
  Custom key-value metadata.
</ParamField>

<ParamField body="scheduledAt" type="Date">
  Schedule the email for future delivery.
</ParamField>

<Note>
  All emails are queued for reliable delivery with automatic retries. Use [webhooks](/receiving/webhooks) or [event streaming](/sending/typescript-sdk#real-time-event-streaming) to track delivery status.
</Note>