@unsent/sdk
v1.0.5
Published
TypeScript SDK for the Unsent API - Send transactional & marketing emails with ease
Maintainers
Readme
@unsent/sdk SDK
The official TypeScript SDK for the Unsent API. Send transactional emails, manage contacts, campaigns, and more with ease.
Prerequisites
Installation
NPM
npm install @unsent/sdkYarn
yarn add @unsent/sdkPNPM
pnpm add @unsent/sdkBun
bun add @unsent/sdkUsage
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: "[email protected]",
from: "[email protected]",
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: "[email protected]", from: "[email protected]", subject: "Hi", html: "<p>Hi</p>" },
{ to: "[email protected]", from: "[email protected]", subject: "Hello", html: "<p>Hello</p>" }
];
const { data, error } = await client.emails.batch(emails);Schedule Email
const { data, error } = await client.emails.send({
to: "[email protected]",
from: "[email protected]",
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: "[email protected]",
firstName: "John",
lastName: "Doe",
metadata: { role: "Admin" }
});List Contacts
const { data, error } = await client.contacts.list("contact_book_id", {
page: 1,
limit: 20,
emails: "[email protected]",
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: "[email protected]",
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: "[email protected]",
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: "[email protected]",
reason: "COMPLAINT"
});Delete Suppression
const { data, error } = await client.suppressions.delete("[email protected]");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
