TypeScript SDK

Install#

npm install @poststack.dev/sdk

bun add, pnpm add and yarn add work the same way. The package ships ES module and CommonJS builds with bundled type declarations and has no runtime dependencies. It calls the global fetch, AbortSignal.timeout and Web Crypto (crypto.randomUUID, crypto.subtle), so it runs on Bun, Deno, edge runtimes and any maintained Node.js release.

Create a client#

import { PostStack } from '@poststack.dev/sdk';

const poststack = new PostStack(process.env.POSTSTACK_API_KEY!, {
  // All three options are optional; these are the defaults.
  baseUrl: 'https://api.poststack.dev',
  timeoutMs: 30_000,
  maxRetries: 3,
});

const { id } = await poststack.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Hello from PostStack',
  html: '<p>Welcome!</p>',
});

apiKeystringrequired

An sk_live_… or sk_test_… key, sent as Authorization: Bearer on every request. A test key records sends but never delivers them — see Test mode.

options.baseUrlstringdefault https://api.poststack.dev

API origin. Paths are appended without an /api prefix (/emails, not /api/emails). A trailing slash is stripped.

options.timeoutMsnumberdefault 30000

Timeout for each individual attempt, not for the call as a whole. A timed-out attempt counts as a network error and is retried.

options.maxRetriesnumberdefault 3

Extra attempts after the first, so one call makes at most maxRetries + 1 requests. 0 disables retrying.

Every request also carries User-Agent: PostStack-TypeScript-SDK/0.15.0. Each resource is a property of the client (poststack.emails, poststack.domains, …); the full list is in Method reference.

Retries and idempotency#

The client retries a request when the network fails, the attempt times out, or the API answers 408 or any 5xx. When the response carries Retry-After it waits that long; otherwise it waits a random delay between 0 and 250 ms × 2^attempt (full-jitter exponential backoff).

A 429 is retried only when it carries Retry-After, which the per-minute request limit always sends. The monthly plan limit, the daily sending cap and the new-account sending pause (monthly_limit_exceeded, daily_limit_exceeded, send_limit_exceeded) also answer 429, and are thrown at once whatever the headers say, because waiting a few seconds will not change the answer. So is any Retry-After longer than 60 seconds: the error carries it as retryAfter and you decide whether to wait. Any other error status is thrown at once.

Every POST gets a fresh Idempotency-Key header (a random UUID), generated once per call so all retries of that call share it. The API honours the header on POST /emails, POST /emails/send and POST /emails/batch: a retry after a lost response replays the original send instead of delivering a second copy. Other POST endpoints ignore it, so a retried create elsewhere can still produce a duplicate.

Errors#

Any non-2xx response that is not retried (or is still failing when retries run out) is thrown as a PostStackError. Network failures and timeouts that exhaust the retries are rethrown as the underlying error (a TypeError from fetch, or a TimeoutError DOMException), not wrapped.

import { PostStack, PostStackError } from '@poststack.dev/sdk';

try {
  await poststack.emails.send({
    from: 'you@unverified-domain.com',
    to: ['user@example.com'],
    subject: 'Hello',
    html: '<p>Hi!</p>',
  });
} catch (error) {
  if (error instanceof PostStackError) {
    error.statusCode; // 422
    error.code;       // "unprocessable_entity"
    error.message;    // "Domain 'unverified-domain.com' is not verified"
    error.requestId;  // value of X-Request-Id — quote it to support
  }
  throw error;
}

statusCodenumber

The HTTP status.

messagestring

The API's error field; the status text if the body was not JSON, or Unknown error if it was JSON without an error field.

codestring | undefined

The stable machine-readable code, e.g. invalid_request, unauthorized, forbidden, not_found, conflict, unprocessable_entity, rate_limit_exceeded. Branch on this, not on message.

requestIdstring | undefined

The X-Request-Id response header.

retryAfternumber | undefined

Seconds from the Retry-After header, when the response had one.

headersHeaders | undefined

All response headers, e.g. X-RateLimit-Limit and X-RateLimit-Reset.

Every code and what triggers it is on Errors.

IDs#

Most resources are addressed by a prefixed public ID string (em_…, con_…, seg_…, tpl_…, …). Domains, webhooks, API keys, contact properties, inbound emails, mailbox aliases and webhook deliveries take a numeric id instead, and the method signatures below are typed accordingly.

Pagination#

Methods that return PaginatedResponse<T> accept page (default 1) and per_page (default 20, maximum 100) and resolve to { data: T[], meta: { page, perPage, total, totalPages } }. Three paginated methods keep their endpoint's own envelope: webhooks.getDeliveries() resolves to { deliveries, pagination }, domains.getDmarcReports() to { reports, pagination } (and takes perPage, not per_page), and notificationChannels.getDeliveries() to { deliveries, meta }. Unpaginated methods take no parameters and return the whole collection under a named key ({ domains }, { segments }, { webhooks }, …) exactly as the table shows.

let page = 1;
for (;;) {
  const { data, meta } = await poststack.contacts.list({ page, per_page: 100 });
  for (const contact of data) handle(contact);
  if (page >= meta.totalPages) break;
  page++;
}

Common tasks#

Send and inspect email

// One email, with an attachment (base64 content, 10 MB per file, 25 MB per email)
const res = await poststack.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: ['user@example.com'],
  subject: 'Your invoice',
  html: '<p>Attached.</p>',
  tags: ['invoice'],
  attachments: [{ filename: 'invoice.pdf', content: pdfBase64, content_type: 'application/pdf' }],
});
if (res.test_mode) console.warn('Sent with a test key — nothing was delivered');

// From a published template
await poststack.emails.send({
  from: 'Acme <hello@yourdomain.com>',
  to: ['user@example.com'],
  template_id: 'tpl_abc123',
  variables: { first_name: 'Alice' },
});

// Up to 100 per batch; each element succeeds or fails on its own
const { data } = await poststack.emails.batch({ emails });
const failed = data.filter((r): r is { error: string } => 'error' in r);

// Status and event timeline — pass the em_ publicId
const email = await poststack.emails.get('em_abc123');
const events = await poststack.emails.getEvents('em_abc123');

Verify a webhook

PostStack.Webhooks.verify is static: it needs no client and no API key, only the raw request body, the X-PostStack-Signature header and the signing secret returned by webhooks.create() or webhooks.rotateSecret(). It resolves to false (never throws) on a missing, malformed or non-matching header. During a secret-rotation grace window the header carries two signatures and either one passes.

import { PostStack } from '@poststack.dev/sdk';

export async function POST(req: Request) {
  const body = await req.text(); // the raw body — do not JSON.parse and re-stringify
  const ok = await PostStack.Webhooks.verify(
    body,
    req.headers.get('x-poststack-signature') ?? '',
    process.env.POSTSTACK_WEBHOOK_SECRET!,
  );
  if (!ok) return new Response('invalid signature', { status: 401 });
  const event = JSON.parse(body);
  // …
  return new Response(null, { status: 204 });
}

The same function is exported as WebhooksResource.verify for code that only receives webhooks.

Build a workflow

const workflow = await poststack.workflows.create({
  name: 'Onboarding',
  trigger_type: 'contact.created',
});

// putGraph replaces the whole graph atomically — it is not a merge.
await poststack.workflows.putGraph(workflow.publicId, {
  nodes: [
    { public_id: 'n_trigger', type: 'trigger', config: { triggerType: 'contact.created' }, canvas_x: 0, canvas_y: 0 },
    { public_id: 'n_welcome', type: 'send_email', config: { templateId: 'tpl_welcome' }, canvas_x: 0, canvas_y: 120 },
    { public_id: 'n_wait', type: 'wait', config: { duration: 2, unit: 'days' }, canvas_x: 0, canvas_y: 240 },
  ],
  edges: [
    { from_public_id: 'n_trigger', to_public_id: 'n_welcome' },
    { from_public_id: 'n_welcome', to_public_id: 'n_wait' },
  ],
});

const check = await poststack.workflows.validateGraph(workflow.publicId);
if (check.valid) await poststack.workflows.activate(workflow.publicId);

// Enrol a contact into every active "custom" workflow listening for an event
const { matched } = await poststack.workflows.postEvent({ event: 'order.placed', email: 'user@example.com' });
if (matched === 0) console.warn('No active workflow listens for order.placed');

Method reference#

Every public method in 0.15.0, the request it makes (relative to baseUrl) and what the promise resolves to. Where the API wraps a single object ({ domain }, { contact }, …) the SDK unwraps it, so domains.get() resolves to the Domain itself. { success } is { success: boolean }.

poststack.emails

poststack.domains

poststack.contacts

poststack.contactProperties

poststack.segments

poststack.templates

poststack.broadcasts

poststack.webhooks

poststack.suppressions

poststack.apiKeys

poststack.mailboxes

poststack.inboundEmails

poststack.subscriptionTopics

poststack.workflows

poststack.signupForms

poststack.emailValidations

poststack.notificationChannels

Slack, Discord and Telegram destinations for account events, addressed by their nc_… id. Needs a full_access key. Secrets never come back: responses carry a masked configSummary.

Types#

Every request and response type named in the tables is exported from the package root as a type-only export:

import type {
  SendEmailInput, BatchSendResult, Email, EmailEvent, EmailStatus,
  Domain, DkimRotation, DmarcStats, InboxPlacement,
  Contact, ContactProperty, Segment, Template,
  Broadcast, BroadcastVariantStats, Webhook, WebhookDelivery,
  Mailbox, MailboxFilterRule, InboundEmail, Suppression, ApiKey,
  SubscriptionTopic, ContactSubscription, Workflow, WorkflowGraph,
  WorkflowRun, SignupForm, EmailValidation, EmailPreview, NotificationChannel,
  PaginatedResponse, ListParams,
} from '@poststack.dev/sdk';

Python and Go SDKs#

PostStack also publishes a Python SDK (pip install poststack, version 0.9.0, Python 3.10+) and a Go SDK (go get github.com/getpoststack/go-sdk, version 0.8.0, Go 1.22+). Both decode the response shapes described on this page (numeric id plus publicId on contacts and segments, { deliveries, pagination }, { reports, pagination }, a trigger's run), send the same Idempotency-Key, verify webhook signatures, and follow the same retry rules: Retry-After is honoured up to 60 seconds and a quota 429 is raised at once. Both export contacts as CSV text, optionally for one segment.

Both also have DKIM rotation, inbox placement, webhook batch replay, workflow events and every method added in TypeScript 0.13.0: email preview and spam preview, broadcast performance and non-opener / non-clicker lists, subscription topic get / update / subscribers, contact property option usage, mailbox shares and the unread summary, and the notification channels resource (notification_channels in Python, client.NotificationChannels in Go).

from poststack import PostStack, PostStackError

client = PostStack(api_key="sk_live_...")  # also: base_url=, timeout=30.0, max_retries=3

try:
    result = client.emails.send({
        "from": "Acme <hello@yourdomain.com>",
        "to": ["user@example.com"],
        "subject": "Hello from PostStack",
        "html": "<p>Welcome!</p>",
    })
    print(result["id"])
except PostStackError as err:
    print(err.status_code, err.code, err.error, err.request_id)

# AsyncPostStack has the same resources, with awaitable methods.

client := poststack.NewClient("sk_live_...",
	poststack.WithTimeout(30*time.Second), // also WithBaseURL, WithHTTPClient, WithMaxRetries, WithUserAgent
)

res, err := client.Emails.Send(ctx, &poststack.SendEmailInput{
	From:    "Acme <hello@yourdomain.com>",
	To:      []string{"user@example.com"},
	Subject: "Hello from PostStack",
	Html:    "<p>Welcome!</p>",
})
var apiErr *poststack.Error
if errors.As(err, &apiErr) {
	log.Printf("%d %s: %s (request %s)", apiErr.StatusCode, apiErr.Code, apiErr.Message, apiErr.RequestID)
	if apiErr.IsQuotaExceeded() {
		// monthly limit or daily cap: retrying will not help
	}
}

Method names follow each language's conventions: client.contact_properties.list() in Python, client.ContactProperties.List(ctx) in Go. Python methods return the response as a dict; the pydantic models in poststack.types are there to validate it if you want to. Python's PostStackError has status_code, error, code, request_id, headers and retry_after; Go's *poststack.Error has RetryAfter, Headers, IsRateLimited() and IsQuotaExceeded().

Next steps