Blog
Notes from the
honest side of email
Deliverability, honest analytics and outreach craft — written in plain language, with no growth-hack snake oil.
Earlier articles
253 articles
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 already under pressure. How to back off correctly, not worse.
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.
DeliverabilityField note6 min
AOL Mail has a new owner. Here's what that means if you still send to it
Bending Spoons closed its acquisition of AOL from Yahoo in early 2026. AOL Mail still has tens of millions of users — here's what's known and unknown for senders.
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 rate-limits you and hides partial failures. 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.
DeveloperAnalysis6 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.