Author
Gabriel Lara
Writes the developer side of Norbelys: the SDK, the API, the CLI, the MCP server, and the data-governance details that keep a shared multi-tenant database safe.
Developer Relations, Norbelys at Norbelys
- Developer tooling
- API design
- Data governance
Articles by Gabriel Lara
37 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.
Compliance7 min
Cold email under Australia's Spam Act: consent, identification, and inferred consent for B2B
The Spam Act 2003 requires consent before you send. Here's how inferred consent works for B2B outreach, what a designated commercial electronic message actually is, and the ID rules.
Compliance7 min
Cold email under Brazil's LGPD: legitimate interest and how it compares to GDPR
LGPD is modeled closely on GDPR, and legitimate interest works for B2B cold email in Brazil too. Here's the ANPD's own balancing-test guidance and where LGPD actually diverges from GDPR.
Compliance7 min
CCPA/CPRA and cold email: it's a privacy law, not an anti-spam law
California's CCPA/CPRA gives residents rights over their data, but it doesn't set cold-email consent rules like CASL or GDPR. Here's what it actually changes for a B2B sender.
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.
ComplianceAnalysis9 min
CAN-SPAM vs. GDPR vs. CASL: the cold-email compliance landscape compared
CAN-SPAM, GDPR, and CASL run on three different consent models. A practical comparison on consent, unsubscribe timing, and penalties — not legal advice, just the landscape.
ComplianceAnalysis7 min
Data minimization for cold email: collect less, keep less, risk less
Every field on a contact record can leak, go stale, or need erasing later. Why keeping less data is a deliverability and security strategy, not just a compliance checkbox.
Compliance7 min
Cold email under CASL: how implied consent actually works for B2B outreach
CASL is opt-in by default, but implied consent covers real B2B outreach. Here's the existing-business-relationship window, the conspicuous-publication test, and required message content.
Compliance8 min
Cold email under the GDPR: legitimate interest, the balancing test, and ePrivacy
GDPR doesn't ban B2B cold email. Here's the legitimate-interest basis senders actually rely on, what the balancing test requires, and how ePrivacy layers on top.
Compliance8 min
Cold email in the UK post-Brexit: UK GDPR, PECR, and the corporate-subscriber rule
UK GDPR started as a copy of EU GDPR but is diverging under the Data (Use and Access) Act 2025. Here's what changed, and PECR's corporate vs. individual subscriber split for B2B email.
Compliance7 min
The right to erasure and cold email: what actually has to disappear
A policy guide to GDPR erasure requests in cold outreach: what personal data must go, what aggregate data can stay, and why the erased address gets suppressed forever.
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.
Compliance8 min
What a real data export looks like when you leave a cold-email platform
What a real data export should include when you leave a platform, using Norbelys's actual export bundle — plus the suspend-vs-delete distinction and grace period behind it.
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.