@nextbridgeafrica/sendhivv

Unofficial Node.js SDK for the Sendhivv email API.
Built and maintained by the Nextbridge Africa community.
Not affiliated with or endorsed by the Sendhivv team.

Installation

npm install @nextbridgeafrica/sendhivv
# or
yarn add @nextbridgeafrica/sendhivv

Quick Start

import Sendhivv from "@nextbridgeafrica/sendhivv";
// CommonJS: const Sendhivv = require("@nextbridgeafrica/sendhivv");

const sendhivv = new Sendhivv("YOUR_API_KEY");

const { id } = await sendhivv.emails.send({
  from: "Your App <[email protected]>",
  to: "[email protected]",
  subject: "Welcome aboard",
  template_key: "brand-layout",
  html: "<p>Hi there, your account is ready.</p>",
});

console.log("Sent! ID:", id);

API Reference

new Sendhivv(apiKey, options?)

| Param | Type | Description | |---|---|---| | apiKey | string | Your Sendhivv API key (required) | | options.baseUrl | string | Override the API base URL (optional) |

sendhivv.emails

emails.send(params)

Send a single transactional email.

await sendhivv.emails.send({
  from: "Acme <[email protected]>",
  to: ["[email protected]", "[email protected]"], // or a single string
  subject: "Your order shipped!",
  html: "<strong>It's on its way.</strong>",
  text: "It's on its way.",           // optional plain-text fallback
  template_key: "shipping-update",    // optional Sendhivv template
  cc: "[email protected]",             // optional
  bcc: "[email protected]",            // optional
  reply_to: "[email protected]",       // optional
  headers: { "X-Custom": "value" },   // optional custom headers
  variables: { order_id: "ORD-123" }, // optional template vars
  attachments: [
    {
      filename: "invoice.pdf",
      content: "<base64-string>",
      content_type: "application/pdf",
    },
  ],
});

emails.get(id)

Retrieve a previously sent email.

const email = await sendhivv.emails.get("email_id_here");
console.log(email.status);

emails.cancel(id)

Cancel a scheduled email before it sends.

await sendhivv.emails.cancel("email_id_here");

emails.update(id, params)

Update a scheduled email.

await sendhivv.emails.update("email_id_here", {
  subject: "Updated subject",
});

sendhivv.batch

batch.send(emails[])

Send up to 100 emails in a single API request.

const { data } = await sendhivv.batch.send([
  {
    from: "App <[email protected]>",
    to: "[email protected]",
    subject: "Hello User 1",
    html: "<p>Hi 1</p>",
  },
  {
    from: "App <[email protected]>",
    to: "[email protected]",
    subject: "Hello User 2",
    html: "<p>Hi 2</p>",
  },
]);

data.forEach(({ id }) => console.log("Sent:", id));

sendhivv.domains

domains.list()

List all sending domains on your account.

const { data } = await sendhivv.domains.list();

domains.get(id)

Get a domain by ID.

const domain = await sendhivv.domains.get("dom_id");

domains.create({ name })

Register a new sending domain.

const domain = await sendhivv.domains.create({ name: "mail.acme.com" });

domains.verify(id)

Trigger DNS verification for a domain.

await sendhivv.domains.verify("dom_id");

domains.remove(id)

Remove a domain.

await sendhivv.domains.remove("dom_id");

Error Handling

All errors are typed. Import them for precise catch blocks:

import Sendhivv, {
  AuthenticationError,
  ValidationError,
  RateLimitError,
} from "@nextbridgeafrica/sendhivv";

try {
  await sendhivv.emails.send({ ... });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("Bad API key");
  } else if (err instanceof ValidationError) {
    console.error("Invalid params:", err.message);
  } else if (err instanceof RateLimitError) {
    console.error("Slow down!");
  } else {
    throw err;
  }
}

| Class | Status | |---|---| | AuthenticationError | 401 | | ValidationError | 422 | | NotFoundError | 404 | | RateLimitError | 429 | | InternalServerError | 500/502/503 | | SendhivvError | base class for all above |

TypeScript

Full type definitions are bundled — no @types/ package needed.

import Sendhivv, { SendEmailParams, Email } from "@nextbridgeafrica/sendhivv";

Contributing

This SDK is open to contributions from the Nextbridge Africa community. PRs welcome!

1. Fork the repo
2. npm run build after changes
3. Open a pull request

License

MIT — see LICENSE.

Disclaimer: This is an unofficial community SDK maintained by Nextbridge Africa. It is not maintained by or affiliated with Sendhivv.