Introducing the Postscale Node.js SDK

Postscale now has an official Node.js and TypeScript SDK on npm: @postscale/postscale.

The first release is built for server-side Node.js 20+ applications. It wraps the public Postscale API, keeps the same request fields you see in the REST docs, and adds the pieces most teams otherwise write by hand: typed result objects, attachment helpers, and webhook signature verification.

Install

npm install @postscale/postscale

Set your API key in the environment:

POSTSCALE_API_KEY=ps_live_your_api_key

API keys should only be used from trusted server-side code. Do not ship them in browser bundles.

Send Your First Email

import { Postscale } from "@postscale/postscale";

const postscale = new Postscale(process.env.POSTSCALE_API_KEY);

const { data, error } = await postscale.emails.send({
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Welcome to Postscale",
  html_body: "<strong>It works.</strong>",
});

if (error) {
  throw new Error(error.message);
}

console.log(data?.message_id);

Before production sending, add and verify your sending domain in Postscale so SPF, DKIM, DMARC, and return-path bounce tracking are configured correctly. The Getting Started guide covers that flow end to end.

API-Native by Design

The SDK keeps Postscale request fields in snake_case.

That is intentional. The same payload works across SDK examples, REST examples, OpenAPI tooling, logs, and support conversations:

await postscale.emails.send({
  from: "orders@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Receipt",
  html_body: "<p>Thanks for your order.</p>",
  text_body: "Thanks for your order.",
  metadata: {
    order_id: "ord_123",
  },
});

There is less translation layer to learn, and fewer edge cases where a field name differs between SDK and HTTP usage.

Result Objects Instead of Throw-Only Flows

Resource methods return { data, error, headers }:

const { data, error, headers } = await postscale.emails.send({
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Welcome",
  html_body: "<strong>Hello</strong>",
});

if (error) {
  console.error(error.code, error.message, headers.requestId);
  return;
}

console.log(data?.status);

The SDK does not automatically retry non-idempotent email sends. That keeps applications from accidentally duplicating customer email until the send API has an explicit idempotency contract.

Attachments

For file attachments, use the helper instead of manually base64-encoding the file:

import { Postscale, attachmentFromFile } from "@postscale/postscale";

const postscale = new Postscale();

const { error } = await postscale.emails.send({
  from: "billing@yourdomain.com",
  to: ["customer@example.com"],
  subject: "Invoice #1234",
  html_body: "<p>Your invoice is attached.</p>",
  attachments: [
    await attachmentFromFile("./invoice-1234.pdf", "application/pdf"),
  ],
});

if (error) {
  throw new Error(error.message);
}

The SDK checks the documented attachment limits before sending.

Webhook Verification

Postscale signs webhook deliveries with X-Postscale-Signature. The SDK verifies the timestamped t=...,v1=... format and supports multiple secrets during rotation windows:

import { verifyWebhookSignature } from "@postscale/postscale";

const result = verifyWebhookSignature(
  rawBody,
  request.headers.get("x-postscale-signature"),
  process.env.POSTSCALE_WEBHOOK_SECRET,
);

if (!result.valid) {
  return new Response(result.message, { status: 401 });
}

Use the raw request body bytes for verification. Do not parse JSON and re-serialize it before verifying the signature.

What Is Included

The initial SDK covers public product APIs:

• emails
• domains
• dkim
• aliases
• inbound
• stats
• warming
• suppressions
• webhooks
• templates
• usage
• trust

It intentionally does not include billing, invoices, onboarding, browser auth, MFA, API-key management, admin routes, Stripe webhooks, unsubscribe endpoints, or contact forms.

What Is Next

Node.js is the first SDK. The roadmap continues with Python, PHP/Laravel, Go, Ruby, Java/Kotlin, .NET, and Rust once the public OpenAPI contract is ready for each ecosystem.

Start with the SDKs and HTTP Clients guide, or install the package from npm.