@sendbyte/node

The official Node.js SDK for SendByte, the email API for Africa. Zero runtime dependencies, full TypeScript types, and a surface that maps one to one onto the REST API.

Install

npm install @sendbyte/node

Requires Node 18 or newer (the SDK uses the built in fetch). ESM and CommonJS are both published.

Quickstart

import { SendByte } from '@sendbyte/node';

const sendbyte = new SendByte('sk_test_...');

const email = await sendbyte.emails.send({
  from: 'PayLink <receipts@paylink.ng>',
  to: 'amaka@halo.ng',
  subject: 'Receipt for your payment',
  html: '<p>Thank you. Your payment was received.</p>',
});

console.log(email.id);

Keys that start with sk_test_ run in the sandbox: every endpoint behaves the same, but nothing is actually delivered. Switch to an sk_live_ key when you are ready to send for real.

Configuration

const sendbyte = new SendByte('sk_live_...', {
  baseUrl: 'https://api.sendbyte.africa', // override for self hosted or staging
});

API

Emails

await sendbyte.emails.send({ from, to, subject, html });
await sendbyte.emails.get('em_123');
await sendbyte.emails.list({ limit: 20, status: 'delivered' });

to, cc, bcc, and reply_to accept a single address or an array. Pass idempotency_key to make retries safe, scheduled_at for future sends, and template_id with variables to render a server side template.

Domains

const domain = await sendbyte.domains.create('paylink.ng');
// domain.dns_records lists the SPF, DKIM, and DMARC records to publish
await sendbyte.domains.list();
await sendbyte.domains.get(domain.id);
await sendbyte.domains.verify(domain.id);

Webhooks

const endpoint = await sendbyte.webhooks.create({
  url: 'https://example.com/hooks/sendbyte',
  events: ['email.delivered', 'email.bounced'],
});
// endpoint.secret is shown once, store it now
await sendbyte.webhooks.list();
await sendbyte.webhooks.disable(endpoint.id);
await sendbyte.webhooks.replay('evt_123');

Verifying webhook signatures

Every webhook request carries a sendbyte-signature header. Verify it against the raw request body before trusting the payload.

import { verifyWebhookSignature } from '@sendbyte/node';

app.post('/hooks/sendbyte', (req, res) => {
  const valid = verifyWebhookSignature(
    process.env.SENDBYTE_WEBHOOK_SECRET,
    req.headers['sendbyte-signature'],
    req.rawBody, // the raw, unparsed body
  );
  if (!valid) return res.status(401).end();
  // handle req.body
  res.status(200).end();
});

The check rejects missing, malformed, tampered, and stale signatures (default tolerance is 300 seconds).

Errors

Failed requests throw a SendByteError carrying the API error shape.

import { SendByteError } from '@sendbyte/node';

try {
  await sendbyte.emails.send({ from, to, subject, html });
} catch (err) {
  if (err instanceof SendByteError) {
    console.error(err.code, err.status, err.message, err.docsUrl);
  }
}

Links

• Documentation: https://docs.sendbyte.africa
• API reference: https://docs.sendbyte.africa

License

MIT