@unsent/sdk SDK

The official TypeScript SDK for the Unsent API. Send transactional emails, manage contacts, campaigns, and more with ease.

Prerequisites

• unsent API key
• Verified domain

Installation

NPM

npm install @unsent/sdk

Yarn

yarn add @unsent/sdk

PNPM

pnpm add @unsent/sdk

Bun

bun add @unsent/sdk

Usage

Basic Setup

import { unsent } from "@unsent/sdk";

const client = new unsent("un_xxxx");

Environment Variables

You can also set your API key using environment variables:

// Set UNSENT_API_KEY in your environment
// Then initialize without passing the key
const client = new unsent();

Emails

Send Email

const { data, error } = await client.emails.send({
  to: "hello@acme.com",
  from: "hello@company.com",
  subject: "unsent email",
  html: "<p>unsent is the best email service provider</p>",
  text: "unsent is the best email service provider",
});

if (error) {
  console.error("Error:", error);
} else {
  console.log("Email sent! ID:", data.id);
}

Get Email

const { data, error } = await client.emails.get("email_id");

Send Batch Emails

const emails = [
   { to: "user1@example.com", from: "hello@company.com", subject: "Hi", html: "<p>Hi</p>" },
   { to: "user2@example.com", from: "hello@company.com", subject: "Hello", html: "<p>Hello</p>" }
];

const { data, error } = await client.emails.batch(emails);

Schedule Email

const { data, error } = await client.emails.send({
  to: "hello@acme.com",
  from: "hello@company.com",
  subject: "Scheduled email",
  html: "<p>This is scheduled</p>",
  scheduledAt: "2024-12-25T10:00:00Z",
});

Cancel Scheduled Email

const { data, error } = await client.emails.cancel("email_id");

Contacts

Create Contact

const { data, error } = await client.contacts.create("contact_book_id", {
  email: "user@example.com",
  firstName: "John",
  lastName: "Doe",
  metadata: { role: "Admin" }
});

List Contacts

const { data, error } = await client.contacts.list("contact_book_id", {
  page: 1,
  limit: 20,
  emails: "user@example.com",
  ids: "id1,id2"
});

Get Contact

const { data, error } = await client.contacts.get("contact_book_id", "contact_id");

Update Contact

const { data, error } = await client.contacts.update("contact_book_id", "contact_id", {
  firstName: "Jane"
});

Upsert Contact

const { data, error } = await client.contacts.upsert("contact_book_id", "contact_id", {
  email: "user@example.com",
  firstName: "John"
});

Delete Contact

const { data, error } = await client.contacts.delete("contact_book_id", "contact_id");

Contact Books

List Contact Books

const { data, error } = await client.contactBooks.list();

Create Contact Book

const { data, error } = await client.contactBooks.create({
  name: "Newsletter Subscribers",
  emoji: "📧"
});

Get Contact Book

const { data, error } = await client.contactBooks.get("book_id");

Update Contact Book

const { data, error } = await client.contactBooks.update("book_id", {
  name: "New Name"
});

Delete Contact Book

const { data, error } = await client.contactBooks.delete("book_id");

Campaigns

Create Campaign

const { data, error } = await client.campaigns.create({
  name: "Monthly Newsletter",
  from: "news@company.com",
  subject: "January Updates",
  contactBookId: "book_id",
  html: "<h1>News</h1>",
  sendNow: false // set to true to send immediately
});

Get Campaign

const { data, error } = await client.campaigns.get("campaign_id");

Schedule Campaign

const { data, error } = await client.campaigns.schedule("campaign_id", {
  scheduledAt: "2025-01-01T09:00:00Z",
  batchSize: 500
});

Pause/Resume Campaign

await client.campaigns.pause("campaign_id");
await client.campaigns.resume("campaign_id");

Templates

List Templates

const { data, error } = await client.templates.list();

Create Template

const { data, error } = await client.templates.create({
  name: "Welcome Email",
  subject: "Welcome {{name}}",
  html: "<h1>Welcome!</h1>"
});

Get Template

const { data, error } = await client.templates.get("template_id");

Update Template

const { data, error } = await client.templates.update("template_id", {
  subject: "New Subject"
});

Delete Template

const { data, error } = await client.templates.delete("template_id");

Webhooks

Note: Webhooks are currently in development. The following methods are placeholders for future implementation.

List Webhooks

const { data, error } = await client.webhooks.list();

Create Webhook

const { data, error } = await client.webhooks.create({
  url: "https://api.myapp.com/webhooks/unsent",
  events: ["email.sent", "email.opened"]
});

Update Webhook

const { data, error } = await client.webhooks.update("webhook_id", {
  events: ["email.bounced"]
});

Delete Webhook

const { data, error } = await client.webhooks.delete("webhook_id");

Domains

List Domains

const { data, error } = await client.domains.list();

Create Domain

const { data, error } = await client.domains.create({
  domain: "mail.example.com"
});

Verify Domain

const { data, error } = await client.domains.verify("123"); // Uses domain ID (string)

Get Domain

const { data, error } = await client.domains.get("123");

Delete Domain

const { data, error } = await client.domains.delete("123");

Analytics

Get General Analytics

const { data, error } = await client.analytics.get();

Get Time Series

const { data, error } = await client.analytics.getTimeSeries({
  days: 30,
  domain: "example.com"
});

Get Reputation

const { data, error } = await client.analytics.getReputation({
  domain: "example.com"
});

Suppressions

List Suppressions

const { data, error } = await client.suppressions.list({
  page: 1,
  limit: 10,
  search: "test",
  reason: "COMPLAINT"
});

Add Suppression

const { data, error } = await client.suppressions.add({
  email: "bad@example.com",
  reason: "COMPLAINT"
});

Delete Suppression

const { data, error } = await client.suppressions.delete("bad@example.com");

API Keys

List API Keys

const { data, error } = await client.apiKeys.list();

Create API Key

const { data, error } = await client.apiKeys.create({
  name: "Prod Key",
  permission: "FULL"
});

Delete API Key

const { data, error } = await client.apiKeys.delete("key_id");

Settings

Get Settings

const { data, error } = await client.settings.get();

Error Handling

The SDK returns a consistent response structure with data and error:

const { data, error } = await client.emails.send({ ... });

if (error) {
  // error: { code: string; message: string; }
  console.error(`Error ${error.code}: ${error.message}`);
  return;
}

console.log("Success:", data);

TypeScript Support

The SDK is fully typed. You can use inferred types:

import { unsent } from "@unsent/sdk";

const client = new unsent();
// Types are automatically inferred
const { data } = await client.domains.list();

License

MIT

Support

• Documentation
• GitHub Issues
• Discord Community