@nilovonjs/connect

Official TypeScript SDK for the Nilovon Connect API.

• Homepage: https://connect.nilovon.com
• API host: https://api.connect.nilovon.com
• Documentation: https://docs.connect.nilovon.com

Installation

npm install @nilovonjs/connect
# or
pnpm add @nilovonjs/connect
# or
yarn add @nilovonjs/connect
# or
bun add @nilovonjs/connect

Quick Start

import { NilovonConnect } from "@nilovonjs/connect";

const client = new NilovonConnect({ apiKey: "nk_..." });
// or simply:
// const client = new NilovonConnect("nk_...");

// Send an email
await client.emails.send({
  to: "[email protected]",
  from: "[email protected]",
  subject: "Welcome!",
  html: "<h1>Hello</h1><p>Welcome to our platform.</p>",
});

// Create a campaign
await client.campaigns.create({
  name: "Weekly Newsletter",
  subject: "This week's updates",
  fromEmail: "[email protected]",
});

// List contacts
const { items } = await client.contacts.list({ limit: 50 });

Configuration

| Option | Required | Default | Description | | --------- | -------- | ---------------------------------- | ------------------------- | | apiKey | Yes | — | API key from your dashboard | | baseUrl | No | https://api.connect.nilovon.com | Custom API base URL |

Resources

Emails

// Send a single email
await client.emails.send({
  to: "[email protected]",
  from: "[email protected]",
  subject: "Hello",
  html: "<p>Content here</p>",
  replyTo: "[email protected]",
  scheduledAt: "2025-01-01T10:00:00Z", // optional
});

// Get a message by ID
const message = await client.emails.get("msg_...");

// List messages
const { items } = await client.emails.list({ limit: 20, status: "sent" });

Contacts

await client.contacts.create({ email: "[email protected]", name: "Jane Doe", tags: ["vip"] });
await client.contacts.get("contact_id");
await client.contacts.list({ search: "jane", limit: 50 });
await client.contacts.update("contact_id", { name: "Jane Smith" });
await client.contacts.delete("contact_id");

Campaigns

await client.campaigns.create({ name: "Launch Announcement", subject: "We launched!", fromEmail: "[email protected]" });
await client.campaigns.update({ id: "camp_id", bodyHtml: "<h1>Hello</h1>" });
await client.campaigns.schedule("camp_id"); // send now
await client.campaigns.schedule("camp_id", "2025-06-01T09:00:00Z"); // schedule
await client.campaigns.pause("camp_id");
await client.campaigns.resume("camp_id");
await client.campaigns.duplicate("camp_id");
await client.campaigns.delete("camp_id");

Domains

await client.domains.create("mail.yourdomain.com");
await client.domains.list();
await client.domains.verify("domain_id");
await client.domains.delete("domain_id");

Templates

await client.templates.create({ name: "Welcome", channelType: "email", body: "<p>Hello {{name}}</p>" });
await client.templates.list({ channelType: "email" });
await client.templates.update("tmpl_id", { subject: "Updated subject" });
await client.templates.delete("tmpl_id");

Webhooks

await client.webhooks.create({ url: "https://yourdomain.com/webhook", events: ["message.sent"] });
await client.webhooks.list();
await client.webhooks.update("wh_id", { isActive: false });
await client.webhooks.delete("wh_id");

Webhook Verification

Verify incoming webhook signatures using HMAC-SHA256:

import { NilovonConnect } from "@nilovonjs/connect";

const isValid = await NilovonConnect.verifyWebhook(
  "your_webhook_secret",
  requestBody,
  request.headers["x-webhook-signature"],
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}

Advanced: Raw Client

For advanced usage, access the underlying oRPC client directly:

const client = new NilovonConnect("nk_...");

// Use the raw oRPC client
const result = await client.raw.message.send({ ... });

Error Handling

import { ORPCError } from "@orpc/client";

try {
  await client.contacts.get("nonexistent");
} catch (error) {
  if (error instanceof ORPCError) {
    console.error(error.code, error.message);
  }
}

TypeScript

The SDK is fully typed. Import types as needed:

import type { SendEmailParams, ContactParams, CreateCampaignParams } from "@nilovonjs/connect";