Postbox docs

Install

npm install @postbox/sdk

pip install postbox-sdk

dotnet add package Postbox

<dependency>
  <groupId>cloud.postboxapp</groupId>
  <artifactId>postbox</artifactId>
  <version>0.1.0</version>
</dependency>

go get github.com/postboxapp/postbox-go@latest

Construct

import { Postbox } from "@postbox/sdk";

const pb = new Postbox({ apiKey: process.env.PB_KEY! });

import os
from postbox import Postbox

pb = Postbox(api_key=os.environ["PB_KEY"])

using Postbox;

var pb = new PostboxClient(Environment.GetEnvironmentVariable("PB_KEY")!);

import cloud.postboxapp.Postbox;

Postbox pb = new Postbox(System.getenv("PB_KEY"));

import postbox "github.com/postboxapp/postbox-go"

pb, err := postbox.NewWithKey(os.Getenv("PB_KEY"))

The client is immutable and thread-safe once constructed. One client covers both planes: pb.messages.send(...) and pb.domains.create(...) go through the same transport. Python uses the same options in snake_case (api_key, base_url, project_id, max_retries); .NET uses PostboxOptions in PascalCase (ApiKey, BaseUrl, ProjectId, MaxRetries), and its methods are async (await pb.Messages.SendAsync(...)).

Option	Default	Notes
`apiKey`	required	`pb_live_…` or `pb_tok_…`.
`baseUrl`	`https://api.postboxapp.cloud/v1`	Override for self-host or staging.
`projectId`	none	Sets `X-Project-Id` on every request.
`timeout`	`30000`	Per-attempt timeout in ms, not total.
`maxRetries`	`2`	Extra attempts after the first, so 3 total.
`defaultHeaders`	`{}`	Merged into every request.
`fetch`	platform default	Injectable. Route through your own client or proxy.
`hooks`	none	`onRequest`, `onResponse`, `onRetry`. Observability only.

What the client handles

The client takes care of transport, auth, bounded retries, idempotency, pagination, SSE with resume, typed errors, and webhook verification, so your code stays about the mail and not the plumbing.

Namespaces

pb.messages     pb.mailboxes    pb.domains      pb.folders
pb.webhooks     pb.tokens       pb.apiKeys      pb.account
pb.stats        pb.logs         pb.mailboxGroups
pb.inboundPolicy                pb.senderRules

pb.events.stream(...)     // real-time events, see Events
pb.verifyWebhook(...)     // verify signatures, see Webhooks

Per-call options

Every method takes an options argument:

await pb.messages.send(body, {
  idempotencyKey: `welcome-${user.id}`,
  signal: controller.signal,
  headers: { "X-Trace-Id": traceId },
});

Errors

Typed, so you branch on the class rather than the status code. See Errors for the full table.

import { ValidationError, RateLimitError } from "@postbox/sdk";

Other languages

TypeScript, Python, C# (.NET), Java, and Go are all available today, so retries, backoff, error handling, and signature verification behave the same in every language.

The package names

The official packages are @postbox/sdk on npm, postbox-sdk on PyPI (the Python import is still import postbox), Postbox on NuGet, cloud.postboxapp:postbox on Maven Central, and github.com/postboxapp/postbox-go for Go. One client, both planes, in every language.

The REST API underneath

Every SDK method maps to a documented REST endpoint, and every page in these docs shows the raw HTTP call alongside the SDK. If you prefer to call the API directly, the only two things worth reaching for the SDK over are SSE resume and webhook signature verification, and both pages show how to do them by hand.

SDKs