SDKs

Warmbly publishes official, fully typed SDKs for JavaScript and TypeScript, Python, and Go. Each one wraps the same surface: the REST API, the OAuth2 authorization flows, and the realtime gateway. You get typed resources, auto-pagination, automatic retries, and a live event stream without hand-rolling HTTP. All three are open source and track the v1 API.

Official libraries

Install

npm install warmbly

pip install warmbly

go get github.com/warmbly/warmbly-go

Quickstart

Create an API key in the dashboard under Settings, expose it as WARMBLY_API_KEY, then:

import { Warmbly } from "warmbly";

const warmbly = new Warmbly({ apiKey: process.env.WARMBLY_API_KEY });

// List campaigns (auto-paginated)
for await (const campaign of await warmbly.campaigns.list()) {
  console.log(campaign.id, campaign.name);
}

import os
from warmbly import Warmbly

client = Warmbly(api_key=os.environ["WARMBLY_API_KEY"])

for key in client.api_keys.list():
    print(key.name, key.status)

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/warmbly/warmbly-go"
)

func main() {
	client, err := warmbly.New(warmbly.WithAPIKey("wmbly_..."))
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	page, err := client.Campaigns.List(ctx, nil)
	if err != nil {
		log.Fatal(err)
	}
	for campaign, err := range page.All(ctx) {
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(campaign.Name)
	}
}

Authentication

Every SDK takes a bearer credential, and both credential types run through the same permission gates:

• an API key for your own scripts (prefixed wmbly_)
• an OAuth access token for apps acting on behalf of a workspace (prefixed wmat_)

// warmbly-js
new Warmbly({ apiKey: "wmbly_..." });       // API key
new Warmbly({ accessToken: "wmat_..." });   // OAuth access token

# warmbly-py (falls back to WARMBLY_API_KEY when omitted; any bearer token works)
Warmbly(api_key="wmbly_...")

// warmbly-go
warmbly.New(warmbly.WithAPIKey("wmbly_..."))
warmbly.New(warmbly.WithAccessToken("..."))

For the full authorization-code and client-credentials flows (PKCE and automatic token refresh), see OAuth. For key format, scoping, and rotation, see Authentication.

What every SDK gives you

• Typed REST resources across the whole API: mailboxes, campaigns, contacts, the unibox, analytics, templates, CRM, integrations, and webhooks.
• OAuth2 flows built in: authorization-code with PKCE and client-credentials, plus programmatic OAuth application management.
• A realtime gateway on one resilient WebSocket, with heartbeats, automatic reconnect, and session resume, delivering typed events. See Realtime.
• Resilience by default: automatic retries with exponential backoff and jitter, Retry-After support, and idempotency keys for safe mutation retries.
• Cursor pagination with auto-paging iterators, so you loop over every record without tracking cursors yourself.
• Typed errors carrying the request_id and a machine-readable code, matchable against named sentinels. See Error codes.
• A small footprint: warmbly-js and warmbly-go ship with zero runtime dependencies.

No-code and automation

Prefer a visual builder? Warmbly also ships a community n8n node, n8n-nodes-warmbly, and has first-class Zapier and Make guides.

See also

• API overview for the base URL, versioning, and conventions
• Authentication and OAuth
• Permissions for the scopes each token can carry
• Realtime for the event gateway