posta

Official Node/TypeScript client for the POSTA email API.

npm install @esaart/posta

Usage

import { Posta } from "@esaart/posta";

const posta = new Posta("pa_xxxxxxxx", {
  // baseUrl defaults to https://posta.esaart.studio
  baseUrl: "http://localhost:3000",
});

// Send an email
const { id, status } = await posta.emails.send({
  from: "ESAART <[email protected]>",
  to: "[email protected]",
  subject: "Welcome to ESAART 🎉",
  html: "<h1>You are in!</h1>",
});

// List recent emails
const { data } = await posta.emails.list({ limit: 20 });

API

new Posta(apiKey, options?)

• apiKey — your pa_… key (create one in the dashboard → API Keys).
• options.baseUrl — Posta deployment URL. Default https://posta.esaart.studio.
• options.fetch — custom fetch implementation (optional).
• options.timeoutMs — request timeout. Default 30000.
• options.retries — retries for 429/5xx responses. Default 2.

posta.emails.send(params) → SendEmailResult

from (required), to (string | string[], required), subject (required unless a template supplies one), html and/or text. Optional: replyTo, template

• variables, headers, attachments, idempotencyKey, scheduledAt.

// Template + variables
await posta.emails.send({
  from: "ESAART <[email protected]>",
  to: "[email protected]",
  template: "welcome",
  variables: { name: "Alex" },
});

// Attachments (base64), custom headers, idempotency, scheduled send
await posta.emails.send({
  from: "ESAART <[email protected]>",
  to: ["[email protected]", "[email protected]"],
  subject: "Your receipt",
  html: "<p>Thanks!</p>",
  replyTo: "[email protected]",
  headers: { "X-Entity-Ref-ID": "order_123" },
  attachments: [{ filename: "receipt.pdf", content: base64Pdf, contentType: "application/pdf" }],
  idempotencyKey: "order_123",        // a repeat with the same key won't send twice
  scheduledAt: "2026-06-20T09:00:00Z", // ISO 8601 — future-dates the send
});

posta.emails.batch.send(emails[]) → { object, data }

Up to 100 emails per request (each item supports the same fields as send, including attachments/headers). Each result carries an id or an error.

posta.emails.list({ limit }) → { object, data }

posta.emails.validate(email) / posta.emails.validateBatch(emails[])

Pre-send hygiene (syntax, disposable, typo, role, MX) → { valid, risk, reason, checks }.

Posta.webhooks.verify(rawBody, signature, secret) → boolean

Verify the Posta-Signature header (HMAC-SHA256) on an incoming webhook with that endpoint's secret. Works in Node 18+, browsers, Deno and edge runtimes.

Errors throw a PostaError with .status and .message.

Build / publish

npm install
npm run build   # emits dist/ (JS + .d.ts)
npm publish

Zero runtime dependencies — uses the global fetch (Node 18+, Bun, Deno, edge, browsers).