Appearance

Node.js / TypeScript SDK ​

Install ​

bash
npm install @sendivent/sdk

Requires Node.js 18+ (native fetch).

Quickstart ​

typescript
import { Sendivent } from '@sendivent/sdk';

const client = new Sendivent(process.env.SENDIVENT_API_KEY!);

const res = await client
  .event('welcome')
  .to('user@example.com')
  .payload({ name: 'Alice' })
  .send();

if (!res.isSuccess()) {
  console.error(res.error);
}

Configuration ​

Set SENDIVENT_API_KEY in your environment. The SDK automatically routes requests to the correct API based on your key prefix: test_ → sandbox, live_ → production. See Sandbox vs Production.

Common tasks ​

Send with payload ​

typescript
await client.event('order-shipped')
  .to('user@example.com')
  .payload({ order_id: '12345', tracking_url: 'https://...' })
  .send();

Send to a contact object ​

typescript
await client.event('welcome')
  .to({
    email: 'user@example.com',
    name: 'Alice',
    id: 'user_123',
    plan: 'premium'
  })
  .send();

See Contacts for identifier rules and meta fields.

Force a channel ​

typescript
await client.event('verification')
  .channel('sms')
  .to('+46701234567')
  .send();

See Routing.

Set language ​

typescript
await client.event('welcome')
  .language('sv')
  .to('anders@example.com')
  .send();

See Templates for language variants.

Send to multiple recipients ​

typescript
await client.event('newsletter')
  .to(['user1@example.com', 'user2@example.com'])
  .payload({ subject: 'Monthly Update' })
  .send();

Override template settings ​

typescript
await client.event('invoice')
  .to('user@example.com')
  .overrides({
    email: {
      subject: 'Your Invoice',
      reply_to: 'billing@yourcompany.com'
    }
  })
  .send();

Override brand ​

typescript
await client.event('welcome')
  .to('user@example.com')
  .overrides({
    brand: { logotype: 'https://example.fi/logo.png' }
  })
  .send();

Prevent duplicates ​

typescript
await client.event('order-confirmation')
  .to('user@example.com')
  .idempotencyKey('order-12345')
  .send();

Fire-and-forget ​

Skip await to send without waiting for the response. The request is sent immediately and your code continues.

typescript
client.event('welcome')
  .to('user@example.com')
  .send(); // No await — non-blocking

// Code continues immediately

Ideal for non-critical notifications where you don't need delivery confirmation.

Response and message tracking ​

send() returns a response object with a notification ID you can use to track status.

typescript
const res = await client.event('welcome').to('user@example.com').send();
if (res.isSuccess()) {
  console.log(res.data); // { id: "...", event: "welcome", status: "accepted" }

  // Track notification status and messages
  const notification = await client.notifications(res.data.id);
  console.log(notification.messages); // [{ id, channel, status, sent_at, ... }]
}

See Send API for the full response format.

Error handling ​

typescript
try {
  const res = await client.event('welcome').to('user@example.com').send();
  if (!res.isSuccess()) console.error(res.error);
} catch (err: unknown) {
  console.error('Request failed:', err instanceof Error ? err.message : err);
}

TypeScript types ​

The package exports types for contacts and responses:

typescript
import type { Contact } from '@sendivent/sdk';

const contact: Contact = {
  email: 'user@example.com',
  name: 'Alice',
  id: 'user_123'
};

Methods ​

MethodDescription
event(name)Set event name
to(recipient)Set recipient(s)
from(sender)Set custom sender (verified)
payload(data)Set template data
channel(name)Force channel (email, sms, slack, push, telegram, whatsapp, discord)
contactsAccess the Contacts API
language(code)Set language code
overrides(obj)Override template settings
idempotencyKey(key)Prevent duplicate sends
notifications(id)Get notification status and messages
send()Send (returns Promise)

Contacts ​

Manage contacts and push tokens via the contacts namespace.

Upsert a contact ​

typescript
await client.contacts.upsert({
  id: 'user-123',
  name: 'Alice',
  email: 'alice@example.com',
  push_token: 'ExponentPushToken[...]'
});

Get a contact ​

typescript
const { contact } = await client.contacts.get('user-123');
console.log(contact.pushTokens); // ['ExponentPushToken[...]']

Register push token ​

Additive — doesn't remove existing tokens. Call on app startup.

typescript
await client.contacts.registerPushToken('user-123', expoPushToken);

Remove push token ​

Call on logout to stop sending to this device.

typescript
await client.contacts.removePushToken('user-123', expoPushToken);

Update a contact ​

typescript
await client.contacts.update('user-123', { name: 'Alice Updated' });

Delete a contact ​

Hard delete (GDPR compliance).

typescript
await client.contacts.delete('user-123');

Contact methods ​

MethodDescription
contacts.get(id)Get contact by any identifier
contacts.upsert(data)Create or update contact
contacts.update(id, data)Update existing contact
contacts.delete(id)Hard delete (GDPR)
contacts.registerPushToken(id, token)Register device token (additive)
contacts.removePushToken(id, token)Remove device token

See Push Notifications for the full push setup guide.

Common pitfalls ​

  • Using test_ key in production — lower rate limits and separate database (see Sandbox)
  • Forcing sms without a phone number — send fails (see Routing)
  • Blank template variables — you didn't send required payload/meta fields (see Templates)

See also ​

Released under the MIT License.

Copyright © 2026 Sendivent