Blog · Developer
Build on Norbelys
The SDK, the API, the CLI, and the MCP server — how to build on Norbelys instead of clicking through it.
Developer articles
27 articles
Developer8 min
Authenticating server-to-server with the Norbelys API
API keys, why you rotate them, where to store them safely, and why a key for your own backend is a different risk than a key handed to a third-party agent.
Developer8 min
Building a Slack alert for new replies with the Norbelys API
A practical build: poll GET /v1/messages?direction=inbound for unread replies and post them to Slack, without duplicate alerts or a second inbox to babysit.
DeveloperAnalysis7 min
What should an AI agent be allowed to read and write in your CRM data?
AI agents need different guardrails for CRM data than for sending. A practical framework for what to let one read, write, bulk-edit, or never touch.
Developer7 min
Building an internal ops dashboard on the Norbelys API with an AI agent
A grounded walkthrough of scaffolding a small send-volume and bounce-rate dashboard against the Norbelys API, with an AI coding agent doing the build.
Developer7 min
How to authenticate an AI coding agent against the Norbelys API safely
Never hand a coding agent your production API key. A guide to scoped dev keys, auth.md, and why credential discipline matters more with an agent in the loop.
Developer7 min
Building on the Norbelys API with Claude Code: a practical guide
How to use Claude Code to build a real tool against the Norbelys API — grounding it with the agent kit first, then walking a realistic task end to end.
Developer7 min
Build a research-only outreach agent on Norbelys MCP
Build an agent on Norbelys MCP that researches people, builds segments, and drafts sequences — and is structurally unable to call a send-related tool.
Developer7 min
Connect Claude Code, Cursor, Windsurf, and VS Code to Norbelys over MCP
Step-by-step setup for wiring Claude Code, Claude's custom connectors, Cursor, Windsurf, and VS Code to the Norbelys MCP server, with real commands and configs.
Developer7 min
Scoping the API key you hand an AI agent, on purpose
The MCP credential you hand an agent is the whole permission boundary. Practical key hygiene: dedicated keys, rotation, revocation, and OAuth vs. API keys.
Developer7 min
Automating cold-email ops checks with the Norbelys CLI in CI
A working GitHub Actions example: install the norbelys CLI, authenticate with $NORBELYS_API_KEY, and run a scripted campaign-config check on every push or schedule.
Developer7 min
Managing multiple Norbelys orgs from one terminal with the CLI
How the norbelys CLI's one-profile-per-org config file works, and the safe patterns for switching between client workspaces without hitting the wrong org.
DeveloperAnalysis7 min
CLI vs. dashboard: when scripting cold-email ops actually beats clicking
An honest, non-absolutist take on when the norbelys CLI is the right tool for an operational task, and when the dashboard genuinely serves you better.
Developer7 min
norbelys login: API key vs. browser OAuth, and where your credentials live
The CLI's two auth modes — org-scoped API keys and PKCE browser OAuth — when to use which, and why config.json's 0600 file permission actually matters.
Developer7 min
Installing the Norbelys CLI and running your first command
Two ways to install the norbelys CLI, how it turns the REST API into commands automatically, and a full walkthrough from install to your first real call.
Developer7 min
Event webhooks are on the way: what to use instead, today
Norbelys outbound event webhooks aren't live yet. An honest look at that, plus a guide to cursor-pagination polling and MCP for near-real-time needs today.
Developer7 min
The norbelys Python SDK quickstart: pip install to your first call
Install the official Python SDK from PyPI, authenticate with an API key, and make your first typed call against the Norbelys API — a complete quickstart.
DeveloperAnalysis6 min
Node, Python, Go, or Ruby: which Norbelys SDK should you use?
A practical decision guide to the four official Norbelys SDKs: which fits an edge Worker, a data script, a high-throughput backend, or a Rails app.
DeveloperAnalysis6 min
DELETE /v1/people/:id vs. people:erase: two buttons that look similar and aren't
DELETE archives a contact and is reversible. people:erase is a separate, audited GDPR flow that destroys PII forever. Conflating the two is a real compliance bug.
Developer6 min
Handling Norbelys API rate limits: backoff that doesn't make things worse
A tight retry loop against a 429 doesn't just fail — it adds load to a shared multi-tenant database exactly when it's already under pressure. How to back off correctly.
Developer8 min
The @norbelys/sdk quickstart: from npm install to your first API call
Install the official Node/TypeScript SDK, authenticate with an API key, and make your first typed call against the Norbelys API — a complete quickstart.
Developer6 min
Cursor pagination explained: why the Norbelys API doesn't use page numbers
Page numbers silently skip or double-serve rows when data changes mid-list. Why the Norbelys API paginates on (createdAt, id) instead, with a working example.
Developer6 min
The job pattern: how to bulk-import contacts into Norbelys correctly
Importing 20,000 contacts one POST at a time will rate-limit you and hide partial failures. Here's the job pattern — create a job, poll for progress — and why it exists.
Developer6 min
Typed API errors: handling Norbelys errors without guessing from status codes
A 400 alone tells you nothing useful. How to build error handling around the Norbelys API's structured error shape instead of parsing status codes and hoping.
Developer7 min
Idempotency-Key: stopping a flaky retry from double-firing
What the Idempotency-Key header does on Norbelys's API, why it matters for state-changing POSTs, and what happens to a retried request without one.
Developer7 min
The Norbelys OpenAPI spec: 83 operations, one document
A practical tour of api.norbelys.com/openapi.json: what's in it, how to import it into Postman or Insomnia, and why one spec drives every SDK and the CLI.
DeveloperAnalysis7 min
Why Norbelys's API uses givenName, not first_name
Norbelys's API uses Schema.org fields — givenName, affiliation, sameAs — instead of bespoke names like first_name. The reasoning, plus the mapping table.
Developer8 min
The five patterns behind every Norbelys API endpoint
Every Norbelys REST endpoint is one of five patterns: resource, relationship, view, action, or job. Learn the five and you can predict the whole API.