Node.js SDK

npm install https://tsmart.ai/sdk/node/tsmart-sdk-1.1.1.tgz

import { Tsmart } from "@tsmart/sdk";

// Reads TSMART_API_KEY (and TSMART_BASE_URL, if set)
const tsmart = new Tsmart();

// Or pass the key and options yourself
const custom = new Tsmart("ts_xxxxxxxx_…", {
  timeout: 10_000,
  maxRetries: 3,
});

const { data, error } = await tsmart.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["jane@example.com"],
  subject: "Welcome to Acme",
  html: "<p>Thanks for signing up.</p>",
});

if (error) {
  console.error(error.statusCode, error.name, error.message);
} else {
  console.log("Email id:", data.id);
}

import { readFile } from "node:fs/promises";

const { data, error } = await tsmart.emails.send(
  {
    from: "Acme Billing <billing@acme.com>",
    to: "jane@example.com",
    cc: ["accounts@example.com"],
    reply_to: "support@acme.com",
    subject: "Your invoice INV-1042",
    html: "<p>Your invoice is attached.</p>",
    text: "Your invoice is attached.",
    headers: { "X-Entity-Ref-ID": "INV-1042" },
    tags: [{ name: "category", value: "invoice" }],
    attachments: [
      { filename: "INV-1042.pdf", content: await readFile("INV-1042.pdf"), content_type: "application/pdf" },
    ],
  },
  { idempotencyKey: "invoice-INV-1042" },
);

const { data } = await tsmart.emails.send({
  from: "hello@acme.com",
  to: "jane@example.com",
  subject: "Your trial ends tomorrow",
  text: "Upgrade any time from your account page.",
  scheduled_at: "in 1 day",
});

await tsmart.emails.update(data.id, { scheduled_at: new Date("2026-10-20T09:00:00+03:00") });
await tsmart.emails.cancel(data.id);

// One email, with its html and text while they are kept (3 days) and its tags
const { data: email } = await tsmart.emails.get(id);
console.log(email.last_event); // sent, delivered, bounced, opened …

// Its events in time order
const { data: events } = await tsmart.emails.events(id);
for (const e of events.data) console.log(e.created_at, e.type, e.recipient);

// Recent emails, newest first
const { data: recent } = await tsmart.emails.list({ limit: 50 });

const { data } = await tsmart.emails.metrics({
  start_date: "2026-10-01",
  end_date: "2026-10-07",
  timezone: "Europe/Istanbul",
  granularity: "daily",
  metrics: ["sent", "delivered", "bounced", "delivery_rate", "open_rate"],
  dimensions: ["period"],
});

console.log(data.totals); // { sent: 1200, delivered: 1187, bounced: 4, delivery_rate: 0.9892, open_rate: 0.4103 }
for (const row of data.data) console.log(row.period, row.sent, row.delivered);

const { data, error } = await tsmart.batch.send(
  [
    { from: "hello@acme.com", to: "ana@example.com", subject: "Your weekly digest", html: "<p>…</p>" },
    { from: "hello@acme.com", to: "ben@example.com", subject: "Your weekly digest", html: "<p>…</p>" },
  ],
  { idempotencyKey: "digest-2026-41", validation: "permissive" },
);

console.log(data.data);   // [{ id: "…" }, { id: "…" }]
console.log(data.errors); // [] or [{ index: 1, message: "…" }]

// Add a domain; records lists the DNS records to publish
const { data: domain } = await tsmart.domains.create({ name: "acme.com" });
for (const r of domain.records) console.log(r.type, r.name, r.value);

// After publishing them: prove ownership, then check the sending records
await tsmart.domains.verify(domain.id);
const { data: fresh } = await tsmart.domains.get(domain.id);
console.log(fresh.status); // not_started, pending, partially_verified or verified

await tsmart.domains.update(domain.id, { open_tracking: true, click_tracking: true });
await tsmart.domains.list();
await tsmart.domains.remove(domain.id);

// A key that can only send, and only from one domain
const { data: key } = await tsmart.apiKeys.create({
  name: "Web shop",
  permission: "sending_access",
  domain_id: domain.id,
});
console.log(key.token); // shown only once

await tsmart.apiKeys.list();
await tsmart.apiKeys.update(key.id, { name: "Web shop (production)" });
await tsmart.apiKeys.remove(key.id); // revoked at once

const { data: hook } = await tsmart.webhooks.create({
  endpoint: "https://example.com/hooks/tsmart",
  events: ["email.delivered", "email.bounced"],
});
console.log(hook.signing_secret); // whsec_…, keep it with your receiver

await tsmart.webhooks.test(hook.id); // queues an example email.sent event
await tsmart.webhooks.update(hook.id, { events: ["email.bounced"], status: "enabled" });
await tsmart.webhooks.rotateSecret(hook.id); // the old secret stops working at once

// What was delivered, and how each attempt went
const { data: events } = await tsmart.webhooks.events.list(hook.id);
const eventId = events.data[0].id; // msg_…
await tsmart.webhooks.events.get(hook.id, eventId);
await tsmart.webhooks.events.attempts(hook.id, eventId);
await tsmart.webhooks.events.replay(hook.id, eventId);

await tsmart.webhooks.remove(hook.id);

await tsmart.suppressions.create({ email: "jane@example.com" });
const { data } = await tsmart.suppressions.get("jane@example.com"); // by id or by address
console.log(data.reason); // bounce, complaint or manual

await tsmart.suppressions.list();
await tsmart.suppressions.remove("jane@example.com");

// API requests of the last 30 days, newest first (no bodies are kept)
const { data } = await tsmart.logs.list({ limit: 20 });
for (const l of data.data) console.log(l.created_at, l.method, l.endpoint, l.response_status);

const { data: one } = await tsmart.logs.get(data.data[0].id);
console.log(one.error); // the error name of a failed request, or null

const { data: box, error } = await tsmart.mailboxes.create({
  email: "jane@acme.com",
  first_name: "Jane", // or name: "Jane Doe"
  last_name: "Doe",
  quota_mb: 2048,     // optional: 256 to 51200, lowered to the plan's mailbox size
  org_unit_id: 12,    // optional: default the root unit
});
console.log(box.temporary_password); // shown only once; must be changed at the first sign-in

await tsmart.mailboxes.list({ domain: "acme.com", limit: 100 }); // ordered by address
await tsmart.mailboxes.get("jane@acme.com");
await tsmart.mailboxes.update("jane@acme.com", { name: "Jane Smith", quota_mb: 4096 });
await tsmart.mailboxes.update("jane@acme.com", { active: false }); // suspend; true restores
const { data: reset } = await tsmart.mailboxes.resetPassword("jane@acme.com"); // reset.temporary_password
await tsmart.mailboxes.remove("jane@acme.com"); // with its mail and alternate emails; company owners only

// Alternate emails: mail to them reaches the mailbox, which may also send as them
await tsmart.mailboxes.aliases.create("jane@acme.com", { address: "j.doe@acme.com" });
await tsmart.mailboxes.aliases.list("jane@acme.com");
await tsmart.mailboxes.aliases.remove("jane@acme.com", "j.doe@acme.com");

await tsmart.groups.create({
  address: "team@acme.com",
  name: "Team",
  members: ["jane@acme.com", "partner@example.org"], // mailboxes or outside addresses, up to 200
});
await tsmart.groups.get("team@acme.com");
await tsmart.groups.list({ domain: "acme.com" });

// members is the complete new list: read, change, send back
const { data: team } = await tsmart.groups.get("team@acme.com");
await tsmart.groups.update("team@acme.com", { members: [...team.members, "sam@acme.com"] });

await tsmart.groups.remove("team@acme.com"); // company owners only

let after;
do {
  const { data, error } = await tsmart.emails.list({ limit: 100, after });
  if (error) throw new Error(error.message);
  for (const email of data.data) console.log(email.id, email.last_event);
  after = data.has_more ? data.data.at(-1).id : undefined;
} while (after);

const { data, error } = await tsmart.emails.send(email);
if (error) {
  switch (error.name) {
    case "validation_error":
    case "missing_required_field":
      throw new Error("Bad request: " + error.message);
    case "rate_limit_exceeded":
    case "network_error":
      // try again later, with the same idempotency key
      break;
    default:
      console.error(error.statusCode, error.name, error.message);
  }
}

import { createServer } from "node:http";
import { verifyWebhook, WebhookVerificationError } from "@tsmart/sdk";

createServer(async (req, res) => {
  const chunks = [];
  for await (const chunk of req) chunks.push(chunk);
  try {
    const event = verifyWebhook({
      payload: Buffer.concat(chunks), // the raw body
      headers: req.headers,
      secret: process.env.TSMART_WEBHOOK_SECRET,
    });
    if (event.type === "email.bounced") {
      console.log("Bounced:", event.data.to, event.data.bounce.message);
    }
    res.writeHead(204).end();
  } catch (err) {
    if (!(err instanceof WebhookVerificationError)) throw err;
    res.writeHead(400).end();
  }
}).listen(3000);

export async function POST(request) {
  let event;
  try {
    event = verifyWebhook({
      payload: await request.text(),
      headers: request.headers,
      secret: process.env.TSMART_WEBHOOK_SECRET,
    });
  } catch (err) {
    if (err instanceof WebhookVerificationError) return new Response("Invalid signature", { status: 400 });
    throw err;
  }
  // handle event.type …
  return new Response(null, { status: 204 });
}

import { Tsmart, type Email, type TsmartResponse, type WebhookPayload } from "@tsmart/sdk";

const tsmart = new Tsmart();

const result: TsmartResponse<Email> = await tsmart.emails.get(id);
if (result.error) throw new Error(result.error.message);
console.log(result.data.subject); // result.data is an Email here

function handle(event: WebhookPayload) {
  switch (event.type) {
    case "email.bounced":
      console.log(event.data.email_id, event.data.bounce?.message);
      break;
    case "domain.updated":
      console.log(event.data.name, event.data.status);
      break;
  }
}