Docs / Developers and AI
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/sdkbelongs to a different project: do not install it or enter your OneSend API key into it.
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).
Inside this repository (for example in a script under scripts/), import it by its workspace name. npm workspaces link the name to packages/sdk:
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.
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
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:
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.
Automations and custom events (see Automations):
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.
CLI: onesend
Run the CLI from a checkout after npm install:
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):
echo "alias onesend='node $PWD/packages/sdk/bin/onesend.mjs'" >> ~/.zshrc # or ~/.bashrc
Commands:
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.