npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@postilon/node

v1.2.0

Published

Node.js SDK for the Postilon transactional email API

Readme

@postilon/node

Node.js client for the Postilon transactional email API. Typed, no dependencies, ESM and CommonJS. Needs Node.js 18 or later (it uses the built-in fetch).

Full API documentation: postilon.com/docs.

Install

npm install @postilon/node

Send an email

Create an API key in the dashboard under API Keys, and keep it in an environment variable.

import { Postilon } from "@postilon/node";

const postilon = new Postilon(process.env.POSTILON_API_KEY!);

const email = await postilon.emails.send({
  from: "Acme <[email protected]>",
  to: "[email protected]",
  subject: "Your sign-in code",
  html: "<p>Your code is <strong>482913</strong>.</p>",
  text: "Your code is 482913.",
});
// { id: "msg_…", status: "queued", … }

send takes every field of POST /v1/emails: cc, bcc, reply_to, headers, tags, attachments (Base64 content, or a file_id from postilon.files.upload), template_id with variables, and scheduled_at. CommonJS works too: const { Postilon } = require("@postilon/node").

The client also covers emails.sendBatch, get, list and cancel, and domains, templates, files, suppressions, webhooks and inbound.

Test keys

ps_test_… keys are for development: emails are accepted, rendered and reported like real ones, but nothing is delivered and no credits are used, and any from address works. ps_live_… keys send real mail from a verified domain. The SDK treats both the same.

Idempotency

Pass an idempotency key, such as the order or event ID the email is for, so a retried request never sends twice. It is sent as the Idempotency-Key header:

await postilon.emails.send(
  { from: "[email protected]", to: "[email protected]", subject: "Receipt for order #123", text: "Thanks." },
  { idempotencyKey: "receipt-order-123" },
);

A retry with the same key and body returns the original response. The same key with a different body fails with 409 idempotency_key_reused, so use one key per email.

Errors

When the API answers with an error, the promise rejects with a PostilonError carrying the HTTP status, the code and the message (list of codes). Network failures reject with the error fetch threw.

import { PostilonError } from "@postilon/node";

try {
  await postilon.emails.send({ from: "[email protected]", to: "[email protected]", subject: "Hi", text: "Hi" });
} catch (err) {
  if (err instanceof PostilonError && err.code === "rate_limit_exceeded") {
    // err.rateLimitReset: when the window resets, in Unix seconds (X-RateLimit-Reset)
  } else if (err instanceof PostilonError) {
    console.error(err.status, err.code, err.message); // 403 domain_not_verified …
  } else {
    throw err;
  }
}

A workspace can make 100 requests per second; use emails.sendBatch for many emails at once. 429 daily_limit_reached means the daily sending limit is reached, and retrying within the second will not help. An error response that is not JSON (from a proxy, say) gets the code http_error.

Pagination

Lists return { object: "list", data, count, total, has_more } and take limit (default 100, at most 1000) and offset, newest first:

let offset = 0;
for (;;) {
  const page = await postilon.emails.list({ status: "bounced", limit: 100, offset });
  for (const email of page.data) console.log(email.id, email.to);
  if (!page.has_more) break;
  offset += page.count;
}

Verify webhooks

Each webhook request carries X-Postilon-Signature: t=<unix>,v1=<hex>. Verify it against the raw body, before any JSON parsing, with the endpoint's signing secret (whsec_…, returned when the endpoint is created). Signatures older than 5 minutes are refused; change that with { toleranceSeconds }.

import express from "express";
import { verifyWebhookSignature, type WebhookEvent } from "@postilon/node";

const app = express();

app.post("/webhooks/postilon", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyWebhookSignature(req.body, req.get("X-Postilon-Signature"), process.env.POSTILON_WEBHOOK_SECRET!);
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString("utf8")) as WebhookEvent;
  if (event.type === "email.bounced") {
    // event.data.recipient bounced
  }
  res.sendStatus(200);
});

postilon.webhooks.verifySignature(...) is the same function. Answer with a 2xx within 8 seconds and do slow work afterwards. Events can arrive more than once and out of order, so use the event id to ignore duplicates. See Webhooks.

Receive email

Turn on inbound for a verified domain (or a subdomain of it), and add the MX record it returns:

const domain = await postilon.domains.update("dom_…", { inbound_domain: "reply.acme.com" });
// domain.inbound_record: { type: "MX", name: "reply.acme.com", value: "inbound.postilon.com", priority: 10, … }

Each message then reaches your webhooks as email.received, with its text and HTML (up to 256 KB), attachment list, SPF, DKIM and DMARC results and a spam flag. Narrow on event.type === "email.received" to get event.data typed. Read received email with postilon.inbound.list, get, attachment(id, index) (a Uint8Array) and raw(id) (the message as received). See Inbound email.

License

MIT, see LICENSE.