Email JavaScript SDK

Send transactional email over the HTTPS API from Node and TypeScript with the hepgg package, including queued (over-cap) handling.

Email SDK#

The hepgg package wraps the transactional Email HTTPS API in a typed client. One send() call, sensible client-side guards, and the over-cap queued case surfaced as result.status so you are never surprised by a 202.

Install#

npm install hepgg --registry https://npm.hep.gg

echo 'registry=https://npm.hep.gg' >> .npmrc
npm install hepgg

Send An Email#

Construct Email with your key, then call send(). Provide at least one of html or text.

import { Email } from "hepgg/email";
 
const email = new Email({ token: process.env.HYD_MAIL_KEY });
 
const res = await email.send({
  to: "user@example.com",
  subject: "Welcome to the thing",
  html: "<h1>Hello!</h1>",
  fromName: "Acme",
});
 
console.log(res.messageId, res.status); // "...", "sent"

const { Email } = require("hepgg/email");
 
const email = new Email({ token: process.env.HYD_MAIL_KEY });
email.send({ to: "user@example.com", text: "Hello!" }).then((r) => console.log(r.status));

to, cc, and bcc each accept a string or an array. Billing is one credit per distinct recipient.

Over-Cap Sends Are Queued#

When a sender hits its rolling 24-hour cap the API returns 202 and queues the message. The SDK treats that as success and reports it on status, so you can branch instead of catching.

const res = await email.send({ to: list, subject: "Digest", html });
if (res.status === "queued") {
  console.log("over cap, it will drain within 24h");
}

Guards, Options, Errors#

The client checks the obvious mistakes before spending a request: at least one of html/text, and no more than 100 distinct recipients. Those throw TypeError/RangeError. API failures (credits, rate limit) throw a typed HepError.

import { HepError } from "hepgg";
 
try {
  await email.send({ to: "user@example.com", html: "<p>hi</p>" });
} catch (err) {
  if (err instanceof HepError && err.status === 402) console.error("out of credits");
}

The Email constructor also takes baseURL, timeoutMs, retries, and fetch.

Full Reference#

HTTPS API, Senders, billing, limits, and Errors.