yoursend

Official Node.js SDK for the YourSend multi-channel messaging API.

Send and verify OTPs via email, SMS, voice, WhatsApp, and flashcall — all from a single unified API.

Install

npm install yoursend

Quick Start

import YourSend from 'yoursend';

const ys = new YourSend({ apiKey: 'ys_live_...' });

// Send an email
const { message_id } = await ys.send({
  channel: 'email',
  to: '[email protected]',
  subject: 'Welcome!',
  body: '<h1>Hello from YourSend</h1>',
});

// Send an SMS OTP
const otp = await ys.send({
  channel: 'sms',
  to: '+15551234567',
});

// Verify the OTP
const result = await ys.check({
  message_id: otp.message_id,
  code: '123456',
});

console.log(result.verified); // true

API Reference

Core Methods

ys.send(options) — Send a message

const res = await ys.send({
  channel: 'email',        // 'email' | 'sms' | 'voice' | 'whatsapp' | 'flashcall' | 'auto'
  to: '[email protected]',
  subject: 'Hello',        // email only
  body: '<h1>Hi</h1>',     // html for email, text for sms
  template_id: '...',      // use a saved template
  data: { name: 'Alice' }, // merge tag values
  fallback: 'sms',         // fallback channel on failure
  expires_in: 10,          // OTP expiry in minutes (default: 10)
  tags: ['onboarding'],
});
// => { message_id, status, channel, to, expires_at? }

ys.check(options) — Verify an OTP

const res = await ys.check({
  message_id: '...',
  code: '590075',
});
// => { message_id, status, verified, remaining_attempts? }

ys.status(messageId) — Get delivery status

const msg = await ys.status('msg_...');
// => { id, to_address, channel, status, otp_verified, sent_at, delivered_at, ... }

ys.lookup(phoneNumber) — Phone number lookup

const info = await ys.lookup('+15551234567');
// => { phone_number, country_code, carrier, type }

ys.usage(options?) — Usage statistics

const stats = await ys.usage({ period: 'month' });
// => { period, from, to, total, by_channel: { email: 42, sms: 18 } }

Resource Namespaces

Messages

const { data, pagination } = await ys.messages.list({ page: 1, limit: 20 });
const message = await ys.messages.get('msg_...');

Templates

const { templates } = await ys.templates.list();

const tpl = await ys.templates.create({
  name: 'Welcome',
  channel: 'email',
  subject: 'Welcome {{name}}!',
  html_body: '<h1>Hello {{name}}</h1>',
  merge_tags: ['name'],
});

await ys.templates.update(tpl.id, { description: 'Updated' });
await ys.templates.delete(tpl.id);

Contacts

const { contacts } = await ys.contacts.list({ limit: 50 });

const contact = await ys.contacts.create({
  email: '[email protected]',
  name: 'Alice',
  tags: ['vip'],
});

await ys.contacts.update(contact.id, { name: 'Alice Smith' });

Webhooks

const { webhooks } = await ys.webhooks.list();

const hook = await ys.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['sent', 'delivered', 'verified'],
});
// => { id, url, events, secret }   ← save the secret for HMAC verification

await ys.webhooks.delete(hook.id);

Blasts

const { blasts } = await ys.blasts.list();

const blast = await ys.blasts.create({
  name: 'Product Launch',
  channel: 'email',
  template_id: 'tpl_...',
});

Domains

const { domains, primary_domain } = await ys.domains.list();

const { records } = await ys.domains.create({ domain: 'example.com' });
// => returns DNS records to add

const verification = await ys.domains.verify({ domain: 'example.com' });
// => { domain, status, spf_verified, dkim_verified }

await ys.domains.delete({ domain: 'example.com' });

Error Handling

try {
  await ys.send({ channel: 'email', to: 'bad' });
} catch (err) {
  console.log(err.message);  // "Invalid email format"
  console.log(err.code);     // "invalid_request"
  console.log(err.status);   // 400
}

Configuration

const ys = new YourSend({
  apiKey: 'ys_live_...',
  baseUrl: 'https://api.yoursend.dev', // default
});

License

MIT