---
title: "SDK and CLI"
description: "The TypeScript SDK and the onesend command-line client live in packages/sdk (MIT license)."
url: https://onesend.email/docs/sdk-and-cli/
---
# SDK and CLI

The TypeScript SDK and the `onesend` command-line client live in `packages/sdk` (MIT license).

> The SDK and CLI ship with OneSend and are used from your installation, as described below. The npm package named `@onesend/sdk` belongs to a different project: do not install it or enter your OneSend API key into it.

<a id="sdk"></a>
## TypeScript SDK

The SDK has no runtime dependencies and uses the standard `fetch` API. It ships as TypeScript source and runs where TypeScript runs directly: inside this repository, or with tsx, Bun or Deno. A compiled package for plain Node.js and bundlers is planned. Do not use the SDK in browser code with secret API keys or session tokens; call your own backend instead. For conversion tracking in a web page, use the `/t/onesend.js` script with a Conversion tracking key (see [Marketing](https://onesend.email/docs/marketing/#conversions)).

**Inside this repository** (for example in a script under `scripts/`), import it by its workspace name. npm workspaces link the name to `packages/sdk`:

```ts
import { OneSend } from '@onesend/sdk';
```

Run scripts that use it with `npx tsx script.ts`. Plain `node script.ts` fails with `ERR_MODULE_NOT_FOUND`, because Node cannot resolve the SDK's TypeScript imports.

**From another project**, install it from your checkout by path, so npm never contacts the registry for it. The SDK is an ES module and the examples use top-level `await`, so your project must use ES modules: set `"type": "module"` in its `package.json`, or name your files `.mts`.

```bash
npm pkg set type=module                        # skip if package.json already has "type": "module"
npm install /path/to/onesend/packages/sdk
npm install --save-dev tsx
npx tsx your-script.ts
```

Without `"type": "module"`, tsx stops with `Top-level await is currently not supported with the "cjs" output format`. npm 11 writes `"type": "commonjs"` into new projects by default.

Check that `package.json` in your project lists `"@onesend/sdk": "file:…"`. If it shows a version number instead, the registry package was installed; remove it.

### Usage

```ts
import { OneSend, OneSendError } from '@onesend/sdk';

const onesend = new OneSend({
  apiKey: process.env.ONESEND_API_KEY,   // default: env ONESEND_API_KEY
  baseUrl: 'http://localhost:3000',        // default: env ONESEND_BASE_URL; always set it for self-hosted servers
  maxRetries: 2,                           // 429, 5xx and network errors, exponential backoff, honors Retry-After
});

// Send. An Idempotency-Key is generated automatically and reused across retries.
const { id } = await onesend.emails.send({
  from: 'Acme <hi@acme.dev>',
  to: ['ada@example.com'],
  template: 'receipt',
  variables: { order: { id: 1042, total: 49 }, status: 'paid' },
  tags: ['billing'],
});

// Make retries safe across processes with your own key
await onesend.emails.send(payload, { idempotencyKey: `receipt-${order.id}` });

// Inspect the route it took
const email = await onesend.emails.get(id);
email.attempts.forEach((a) => console.log(a.provider, a.outcome, a.errorCode));

// Iterate every failed email this week
for await (const m of onesend.emails.iterate({ status: 'failed,bounced', from: weekAgo })) console.log(m.id);

// Domains, quota, templates
await onesend.domains.create({ name: 'acme.dev', autoApplyDns: true });
const quota = await onesend.analytics.quota();
const preview = await onesend.templates.render('receipt', { variables: { status: 'failed' } });

try { await onesend.emails.send(bad); }
catch (e) { if (e instanceof OneSendError) console.log(e.status, e.type, e.code, e.requestId); }
```

Send the template slug and `variables` rather than HTML: OneSend renders the template and gives the provider finished HTML, so one template works with every provider and during failover, and template changes in the dashboard need no code change. The `receipt` template in this example must exist in your workspace. Clone one from the gallery first (`await onesend.gallery.clone('receipt-verdant', { slug: 'receipt' })`, or `POST /v1/gallery/receipt-verdant/clone` with `{ "slug": "receipt" }`).

For a one-off email without a template, send the content:

```ts
await onesend.emails.send({ from: 'hi@acme.dev', to: 'ada@example.com', subject: 'Your sign-in code', html: '<p>Your code is <b>482913</b></p>' });
```

Namespaces: `auth`, `emails`, `providers`, `connections`, `policies`, `route`, `domains`, `templates`, `gallery`, `inbox`, `contacts` (including `attributes` and `imports`), `lists`, `segments`, `campaigns` (including `abTest` and `pickAbWinner`), `automations`, `statistics`, `conversions`, `suppressions`, `analytics`, `events` (including `track` for custom events), `apiKeys`, `webhooks`, and `health()`. Types are generated from the same contracts the server validates with.

The `inbox` namespace covers mailboxes (`mailboxes`, `createMailbox`, `createMailboxes`, `updateMailbox`, `deleteMailbox`, `rotateMailboxSecret`, `mailboxMessages`), messages (`list`, `search`, `iterate`, `get`, `update`, `reply`, `compose`, `thread`, `updateThread`) and `notes`, `sent`, `drafts`, `labels`, `members` and `rules` (including `rules.test` for a dry run). See [Inbox](https://onesend.email/docs/inbox/).

Automations and custom events (see [Automations](https://onesend.email/docs/automations/)):

```ts
const a = await onesend.automations.create({
  name: 'Abandoned cart',
  trigger: { type: 'event', name: 'cart_abandoned' },
  goals: [{ kind: 'event', name: 'order_completed' }],
  steps: [
    { type: 'wait', duration: { amount: 1, unit: 'hours' } },
    { type: 'send_email', fromEmail: 'shop@acme.dev', subject: 'You left something in your cart', templateId: 'cart-reminder' },
  ],
});
await onesend.automations.activate(a.id);
await onesend.events.track({ email: 'ada@example.com', name: 'cart_abandoned', properties: { cart_url: 'https://shop.acme.dev/c/1' } });
const report = await onesend.automations.report(a.id);
```

**Other languages.** Use the REST API directly. The OpenAPI 3.1 document at `/openapi.json` has an `operationId` for every operation and a shared `ErrorBody` schema, and works with OpenAPI client generators.

<a id="cli"></a>
## CLI: `onesend`

Run the CLI from a checkout after `npm install`:

```bash
node packages/sdk/bin/onesend.mjs --help   # or, from the repository root: npm run -s onesend -- --help
```

To type `onesend` instead, add an alias to your shell profile (run this from the repository root):

```bash
echo "alias onesend='node $PWD/packages/sdk/bin/onesend.mjs'" >> ~/.zshrc   # or ~/.bashrc
```

Commands:

```bash
onesend login --url http://localhost:3000     # prompts for your key, saves ~/.config/onesend/config.json (mode 0600)
onesend whoami
onesend send --from hi@acme.dev --to ada@example.com --template receipt --var order.id=1042 --var status=paid
onesend send --from hi@acme.dev --to ada@example.com --subject "Hi" --text "Hello"   # one-off, no template
onesend emails ls --status failed --provider resend
onesend emails get msg_…            # shows the route: delivered or failed per provider
onesend domains add acme.dev --auto-dns       # configuration: needs an Admin key
onesend domains verify acme.dev
onesend domains zone acme.dev > acme.zone
onesend connections ls
onesend quota                       # quota usage per provider and in total
onesend templates ls
onesend templates render receipt --var status=failed --out preview.html
onesend mailboxes ls
onesend mailboxes create support@acme.dev --label customers   # configuration: needs an Admin key
onesend mailboxes create @acme.dev --ttl 1h        # random address, deleted after an hour
onesend mailboxes rm support@acme.dev [--delete-messages]
onesend inbox ls --q "is:unread label:billing" --mailbox support@acme.dev
onesend inbox read inb_…
onesend inbox send --from support@acme.dev --to pat@partner.example --subject "Hello" --text "Hi Pat"
```

Commands that change configuration (adding, verifying or removing domains, creating or removing mailboxes) need an **Admin** key; with a Full access or Sending only key they fail with 403 `insufficient_scope`. Admins and owners create one in the dashboard under **API keys → Create key → Permission: Admin**, or with `POST /v1/api-keys` and `"scope": "admin"` from a signed-in session. Keep sending on a Sending only key and use the Admin key only where you set things up.

Every command accepts `--json` for scripting, and `--key` and `--url` to override the saved configuration. The CLI also reads `ONESEND_API_KEY` and `ONESEND_BASE_URL`. Output colors are turned off when `NO_COLOR` is set.

The CLI covers sending, logs, domains, connections, quota, templates, inbox mailboxes and inbox messages. For contacts, lists, campaigns and webhooks, use the dashboard, the SDK or the REST API.
